Build with the API

A REST API at https://api.socialcrm.org/v1 authenticated with API keys. Same account, same plan limits, your data.

Quickstart

First, create an API key in your SocialCRM account, under Settings, API keys. Then list your posts:

curl https://api.socialcrm.org/v1/posts \
  -H "Authorization: Bearer sk_live_..."

const res = await fetch("https://api.socialcrm.org/v1/posts", {
  headers: { Authorization: "Bearer sk_live_..." },
});
const { data } = await res.json();

Authentication

Send your key in the Authorization header on every request:

Authorization: Bearer sk_live_...

You can also send it as X-API-Key: sk_live_.... Keys are bound to one workspace and act as you, within your plan limits.

A key is shown in full only once, when you create it. Store it somewhere safe. If you lose it, revoke it and create a new one.

Scopes

Each key carries a set of scopes. A call that needs a scope your key does not hold returns forbidden_scope.

Scope	What it allows
insights:read	Read analytics, persona, trending, and connected accounts
posts:read	Read posts and drafts
posts:write	Create and edit draft posts
posts:publish	Schedule and publish posts (paid)
ai:generate	Generate AI content (paid, uses quota)
media:write	Upload media (paid)

Rate limits

Each key may make up to 600 requests per minute. Past that, requests return 429 with the standard error envelope:

{"error":{"code":"rate_limited","message":"Too many requests. Slow down and retry."}}

Errors

Every error uses the same envelope:

{"error":{"code":"forbidden_scope","message":"This key cannot publish posts."}}

Code	HTTP	Meaning
`unauthorized`	401	Missing or invalid key
`forbidden_scope`	403	Key lacks the required scope
`payment_required`	402	Action needs a paid plan
`quota_exceeded`	402	Plan quota for this action is used up
`rate_limited`	429	Too many requests for this key
`not_found`	404	Resource does not exist
`invalid_request`	400	Malformed or missing parameters

Pagination

List endpoints take limit (default 20, max 50) and offset. Results come back under a data array:

{"data":[{"id":"post_123"},{"id":"post_124"}]}

Endpoints

Posts

Method	Path	Scope	Description
`GET`	`/v1/posts`	posts:read	List posts
`POST`	`/v1/posts`	posts:write	Create a draft post
`GET`	`/v1/posts/{id}`	posts:read	Get one post
`PATCH`	`/v1/posts/{id}`	posts:write	Update a post
`DELETE`	`/v1/posts/{id}`	posts:write	Delete a post
`POST`	`/v1/posts/{id}/schedule`	posts:publish	Schedule a post
`POST`	`/v1/posts/{id}/publish`	posts:publish	Publish a post now
`GET`	`/v1/posts/{id}/analytics`	insights:read	Get post analytics

AI

Method	Path	Scope	Description
`POST`	`/v1/ai/rewrite`	ai:generate	Rewrite text in your voice
`POST`	`/v1/ai/compose`	ai:generate	Compose a post from a prompt
`POST`	`/v1/ai/hashtags`	ai:generate	Suggest hashtags
`POST`	`/v1/ai/thread`	ai:generate	Expand into a thread
`POST`	`/v1/ai/ideas`	ai:generate	Generate content ideas
`POST`	`/v1/ai/optimise`	ai:generate	Optimise a post for reach

Data

Method	Path	Scope	Description
`GET`	`/v1/accounts`	insights:read	List connected social accounts
`GET`	`/v1/accounts/analytics`	insights:read	Get account analytics
`GET`	`/v1/persona`	insights:read	Get your brand persona
`GET`	`/v1/trending`	insights:read	List trending topics

Media

Method	Path	Scope	Description
`POST`	`/v1/media/upload-url`	media:write	Request a presigned upload URL
`POST`	`/v1/media/{id}/confirm`	media:write	Confirm a finished upload

Example: create a post

curl -X POST https://api.socialcrm.org/v1/posts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"body":"Launch day is here.","account_ids":["acct_1"]}'

# 201 Created
# {"id":"post_123","status":"draft","body":"Launch day is here."}

Example: rewrite with AI

curl -X POST https://api.socialcrm.org/v1/ai/rewrite \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"buy now","tone":"friendly"}'

# 200 OK
# {"data":{"text":"Grab yours today, we would love to have you."}}

Try it

Run a read-only GET against the live API with your own key, right here.

Your key stays in your browser. It is sent only to this API as the Authorization header, never to us, and never stored.

API key

Endpoint