AgentSocial Developer Docs

Agent-first social media management: scheduling, publishing, analytics, AI image/video generation, CRM affiliate pipeline, social listening, and white-label client reports.

Base URL: https://api.getagentsocial.com/api/v1
OpenAPI spec: https://api.getagentsocial.com/docs/json (interactive UI at /docs)
MCP server: https://api.getagentsocial.com/mcp — 13 tools over Streamable HTTP (preferred for AI agents)
Agent summary: /developers/llms.txt
Scopes: /developers/scopes

Authentication

Two options — send the credential on every request:

API key via x-api-key: <key> or Authorization: Bearer <key>.
Create one: POST /api/v1/auth/api-keys with { "name": "my agent", "permissions": ["read","write"] }.
Permissions: read = draft-only · write = full access · admin = + approvals & key management. See scopes.

OAuth 2.0 with PKCE:

POST /oauth/authorize
{ "api_key": "<user api key>", "client_id": "...", "redirect_uri": "...",
  "code_challenge": "<S256 challenge>", "code_challenge_method": "S256",
  "scope": "read write", "state": "xyz" }
→ { "code": "..." }   # 10-minute expiry

POST /oauth/token
{ "grant_type": "authorization_code", "code": "...", "redirect_uri": "...",
  "code_verifier": "...", "client_id": "..." }
→ { "access_token": "...", "refresh_token": "...", "expires_in": 3600, "scope": "read write" }

Then Authorization: Bearer <access_token>. Refresh with grant_type: "refresh_token".

Quickstart

Create an API key — POST /api/v1/auth/api-keys → save the returned key.
List brands — GET /api/v1/brands with your key → pick a brand_id.
List channels — GET /api/v1/channels?brand_id=<id> → connected Instagram/TikTok/… accounts.
Draft a post — POST /api/v1/posts { "brand_id": "...", "content": "Hello world", "channel_ids": ["..."] } → status draft. Add scheduled_at to schedule it.
Check analytics — GET /api/v1/analytics/dashboard?brand_id=<id>&period=30d.

Approval guardrail. Brands may require approval before publishing: draft → in_review → approved → published. A connector must never bypass human review — publishing an unapproved post fails, and read-scoped keys cannot publish or approve at all. This is enforced identically in the REST API and the MCP tools.

MCP (recommended for agents)

Connect any 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

Rate limits

100 requests per minute per credential. Contact support for higher limits.

Key endpoints

Method & path	What it does
`POST /auth/api-keys`	Create an API key
`GET /brands`	List brands
`GET /channels?brand_id=`	List connected social channels
`POST /posts`	Create a draft (or scheduled) post
`GET /posts?brand_id=&status=`	List posts
`POST /posts/:id/submit-for-review`	Move draft → in_review
`POST /posts/:id/approve`	Approve (write/admin)
`POST /posts/:id/publish`	Publish now (write/admin; approval-checked)
`POST /media/`	Upload media (multipart)
`POST /generation/image` · `/video`	AI image / video generation
`GET /generation/jobs/:jobId`	Generation job status
`GET /analytics/dashboard`	Analytics overview
`GET /ai/best-times`	Analytics-based best posting slots
`POST /analytics/export`	Queue a PDF/CSV/XLSX report export
`PUT /brands/:id/report-branding`	White-label agency branding
`POST /listening/keywords`	Track a keyword
`GET /listening/hits`	Social listening hits

Full reference: OpenAPI JSON · interactive Swagger UI