# AgentSocial — llms.txt

AgentSocial is an agent-first social media management platform: schedule and publish posts,
track analytics, generate images/video with AI, manage a CRM affiliate pipeline, run social
listening, and export white-label client reports. Built for AI agents as first-class users.

Base URL: https://api.getagentsocial.com
OpenAPI spec: https://api.getagentsocial.com/docs/json
MCP server (Streamable HTTP): https://api.getagentsocial.com/mcp
Human docs: https://api.getagentsocial.com/developers

## Authentication

Two options. Send credentials on every request.

1. API key — header `x-api-key: <key>` or `Authorization: Bearer <key>`.
   Create one: POST /api/v1/auth/api-keys  { name, permissions: ["read"] | ["read","write"] | ["admin"] }
2. OAuth 2.0 with PKCE —
   POST /oauth/authorize { api_key, client_id, redirect_uri, code_challenge, code_challenge_method: "S256", scope, state }
     → { code } (10-minute expiry)
   POST /oauth/token { grant_type: "authorization_code", code, redirect_uri, code_verifier, client_id }
     → { access_token, refresh_token, expires_in, scope }
   Then use the token as `Authorization: Bearer <access_token>`. Refresh with grant_type "refresh_token".

Scopes (API-key permissions and OAuth scope tokens):
- read   — draft-only. Can create/schedule drafts, generate media, read analytics. CANNOT publish or approve.
- write  — full access. Everything in read, plus publish posts and submit for review.
- admin  — everything in write, plus approve posts, manage API keys, manage report branding.

## Approval guardrail (critical)

Brands may require approval before publishing. The post lifecycle is:
draft → in_review → approved → published (scheduled posts publish automatically at their time).
A connector must NEVER bypass human review. Calling publish on a post that is not approved
for a brand with approval enabled fails with a clear error. draft-only keys (read) cannot
publish or approve at all — those calls are refused. The MCP tools publish_post and
approve_post enforce the same guardrails as the REST API.

## Rate limits

100 requests per minute per credential. Contact support if you need a higher limit.

## Key endpoints (all under https://api.getagentsocial.com/api/v1 unless noted)

- POST /auth/api-keys — create an API key { name, permissions, expires_at }
- GET /brands — list brands
- GET /brands/:id — get a brand
- GET /channels — list connected social channels for a brand (?brand_id=)
- POST /channels/connect — start connecting a new social account
- POST /posts — create a post { brand_id, content, channel_ids[], scheduled_at? }; creates a draft, or scheduled if scheduled_at is set
- GET /posts — list posts (?brand_id=, ?status=draft|in_review|approved|scheduled|published)
- GET /posts/:id — get a post
- POST /posts/:id/submit-for-review — move a draft to in_review
- POST /posts/:id/approve — approve a post that is in review (write/admin only)
- POST /posts/:id/publish — publish now (write/admin; fails if brand requires approval and post is not approved)
- POST /media/ — upload media (multipart); returns a URL usable in posts
- POST /generation/image — generate an image { prompt, brand_id }
- POST /generation/video — generate a video { prompt, brand_id }
- GET /generation/jobs/:jobId — check a generation job's status
- GET /analytics/dashboard — analytics overview (?brand_id=, ?period=7d|30d|90d)
- GET /analytics/posts/:post_id — per-post analytics
- GET /ai/best-times — analytics-based best posting slots (?brand_id=, ?platform=); needs >= 10 analyzed posts, else generic fallback
- POST /analytics/export — queue a report export { brand_id, period, format: pdf|csv|xlsx, branded }
- GET /analytics/exports/:id — export job status; GET /analytics/exports/:id/download — download the file
- PUT /brands/:id/report-branding — white-label settings { agency_name, logo_url, primary_color, accent_color, footer_text }
- POST /listening/keywords — track a keyword { brand_id, keyword, platforms[] }
- GET /listening/hits — social listening hits (?brand_id=, ?reviewed=)
- GET /crm/contacts — list CRM contacts (?brand_id=) [affiliate pipeline]

## MCP tools (preferred for agents)

Connect an MCP client to https://api.getagentsocial.com/mcp with your API key or OAuth token. 13 tools:
list_channels, create_post, schedule_post, list_posts, publish_post, upload_media,
generate_image, generate_video, get_generation_status, submit_for_review, approve_post,
get_analytics, get_best_times. Tool descriptions are written for agent discovery.

## Example user prompts

- "Schedule a post about our new peptide lesson to Instagram tomorrow at 7pm"
- "What were my top 3 posts last week and why did they perform?"
- "Draft a caption for our BPC-157 video, keep it advocate-toned, don't publish it"
- "When should I post on TikTok for maximum engagement?"
- "Generate a lifestyle image for our sleep protocol post and attach it as a draft"