Build with the REST API

Check the reference and your access

The API reference is at /api/v1/docs on your workspace origin. REST requests use an API key in the Authorization header. GET /me/ reports the caller’s scope; GET /accounts/ lists permitted social accounts and their capabilities.

curl "https://YOUR-WORKSPACE-HOST/api/v1/me/" \
  -H "Authorization: Bearer $POSTDELEGATE_API_KEY"

curl "https://YOUR-WORKSPACE-HOST/api/v1/accounts/" \
  -H "Authorization: Bearer $POSTDELEGATE_API_KEY"

Create a draft

Choose a social_account_id returned by /accounts/. Grant create_posts and send action: draft. Replace the example account ID and caption. Use a fresh idempotency key for each new logical post, then retain it for retries of that exact request.

curl -X POST "https://YOUR-WORKSPACE-HOST/api/v1/posts/" \
  -H "Authorization: Bearer $POSTDELEGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR-UNIQUE-REQUEST-ID" \
  --data '{"social_account_id":"ACCOUNT-UUID","caption":"Draft for review","action":"draft"}'

Schedule the reviewed draft

Keep the returned post ID. After required review, an actor with create_posts and publish_directly can POST to /api/v1/posts/{post_id}/schedule with scheduled_at as an ISO 8601 timestamp. GET /api/v1/posts/{post_id} returns its current state. POST /api/v1/posts/{post_id}/cancel cancels a scheduled post back to draft.

• Replace the sample time with your intended future publishing time.
• The v1 API has no post-delete endpoint; manage draft deletion in the web workspace.

{"scheduled_at":"2030-01-15T09:30:00+04:00"}

Handle errors without creating duplicates

REST POST /posts/ accepts Idempotency-Key or the idempotency_key JSON field. Reuse the same key and identical payload when retrying a lost creation response. That replay protection does not make every API operation idempotent.

• 401: check or reissue credentials. 403: check workspace membership, account allowlist and permissions.
• 422: correct the input or workflow state; inspect the returned detail.
• 409 for an identical creation in flight: wait before retrying with the same key.
• 429: respect Retry-After. Do not assume rate-limit headers appear on every successful response.
• A social-platform publish timeout is different from a lost draft-creation response. Review uncertain publication before sending a new post.