Public API

The public API lets scripts, tools (Zapier, n8n) and your own apps list, create, schedule and publish posts, upload media and manage webhooks.

Base URL

https://www.socialpublishai.com/social-publish/api/public/v1

The API is versioned (v1) and only grows: fields and endpoints are added, never removed or renamed inside a version.

A first call

curl https://www.socialpublishai.com/social-publish/api/public/v1/workspaces \
  -H "Authorization: Bearer agp_your_token"

Typical flow

1. GET /workspaces — find your workspace id.
2. GET /workspaces/{id}/accounts — the connected social accounts.
3. POST /workspaces/{id}/posts — create the post (send an Idempotency-Key).
4. POST /workspaces/{id}/posts/{postId}/schedule — schedule it, or …/publish to post now.
5. Listen for post.published / post.failed on a webhook.

Endpoints

Method · path	Token scope
GET /workspaces	posts:read
GET /workspaces/{id}/accounts	posts:read
GET /workspaces/{id}/usage (free, not counted)	posts:read
GET /workspaces/{id}/posts?status&page&size (max 100)	posts:read
GET /workspaces/{id}/posts/{postId}	posts:read
POST /workspaces/{id}/posts	posts:write
PATCH /workspaces/{id}/posts/{postId}	posts:write
DELETE /workspaces/{id}/posts/{postId}	posts:write
POST /workspaces/{id}/posts/{postId}/schedule	posts:publish
PUT /workspaces/{id}/posts/{postId}/schedule (move)	posts:publish
DELETE /workspaces/{id}/posts/{postId}/schedule	posts:publish
POST /workspaces/{id}/posts/{postId}/publish	posts:publish
POST /workspaces/{id}/media/uploads	posts:write
POST /workspaces/{id}/media/{mediaId}/confirm	posts:write
GET /webhooks/event-types	webhooks:read
GET /workspaces/{id}/webhooks, …/{endpointId}/deliveries	webhooks:read
POST, PUT, DELETE …/webhooks…, …/secret, …/test, …/retry	webhooks:write

Every field is in the API reference.

Errors

Errors are RFC 9457 problem details. Show detail to your user — it is written to be read as-is.

{
  "title": "Bad Request",
  "status": 400,
  "detail": "A publish date and time is required."
}