Skip to content

REST API

Authenticate with API keys, call Clautia endpoints and handle confirmations. Explore request examples, errors and usage limits.

Base URL: https://app.clautia.com/api/v1

OpenAPI: https://app.clautia.com/api/v1/openapi.json

Authentication

Use a bearer API key in every request:

curl https://app.clautia.com/api/v1/whoami \
  -H "Authorization: Bearer $CLAUTIA_API_KEY"

whoami returns the key organization and granted scopes.

Endpoints, scopes, and class

Class: R = read, W = write, D = destructive (requires confirmation token).

MethodPathScope(s)Class
GET/whoamikey requiredR
GET/brandsbrands:readR
GET/accountsbrands:readR
GET/postsposts:readR
GET/posts/{postId}posts:readR
POST/postsposts:writeW
POST/posts/{postId}/scheduleposts:writeW*
POST/posts/{postId}/publishposts:writeD
POST/posts/{postId}/cancelposts:writeD
POST/ai/draftai:writeW
POST/ai/adaptai:writeW

* posts_schedule asks for confirmation when scheduling less than 10 minutes ahead.

The AI draft and adapt endpoints support eight networks: Instagram, Facebook, TikTok, X, LinkedIn, YouTube, Threads and Google Business Profile. They do not support Bluesky or Telegram.

Examples

Create a draft post:

curl -X POST https://app.clautia.com/api/v1/posts \
  -H "Authorization: Bearer $CLAUTIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "BRAND_ID",
    "socialAccountIds": ["ACCOUNT_ID"],
    "textDefault": "Hello from Clautia",
    "idempotencyKey": "docs-post-001"
  }'

Schedule a post:

curl -X POST https://app.clautia.com/api/v1/posts/POST_ID/schedule \
  -H "Authorization: Bearer $CLAUTIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduledAt":"2026-12-01T10:00:00Z"}'

Publish now (two-step confirmation):

# Step 1: request token
curl -X POST https://app.clautia.com/api/v1/posts/POST_ID/publish \
  -H "Authorization: Bearer $CLAUTIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Step 2: execute with confirmation token
curl -X POST https://app.clautia.com/api/v1/posts/POST_ID/publish \
  -H "Authorization: Bearer $CLAUTIA_API_KEY" \
  -H "X-Confirmation-Token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors and response format

API errors return:

{ "code": "FORBIDDEN", "message": "Access denied." }

Common codes:

HTTPCodeMeaning
400BAD_REQUESTInvalid request payload
401UNAUTHORIZEDMissing/invalid/revoked key
402PAYMENT_REQUIREDInactive subscription required by paywall
403FORBIDDENScope or role does not allow this action
404NOT_FOUNDResource does not exist in this workspace
409CONFLICTState conflict (idempotency/version)
429TOO_MANY_REQUESTSRate/day budget exceeded
500INTERNAL_SERVER_ERRORUnexpected server error
503SERVICE_UNAVAILABLETemporary capacity issue (Retry-After: 1)

For these validation failures, HTTP 400 uses BAD_REQUEST as the code and the reason below as the message:

MessageMeaning
account_disconnectedA selected account is unavailable or disconnected.
plan_capacity_exceededThe connected channel count exceeds the plan limit.
gbp_location_requiredThe Google Business Profile account needs a location.
gbp_invalid_mediaThe Google Business Profile media is invalid.
destination_requiredChoose a LinkedIn or Facebook destination first.
destination_unknownThat destination is not selected for the account.

Other validation failures use a specific code and a descriptive message:

CodeMeaning
instagram_media_requiredInstagram needs an image or video.
character_limitThe text exceeds a network's character limit.
telegram_caption_limitThe Telegram caption exceeds its media limit.
media_not_uploadedUpload the media to Clautia first.

When a post has a delivery in progress or one that just ran, refresh or publish now answers HTTP 409 with the code recovery_pending: nothing is sent twice at once, and Clautia retries it automatically within minutes. Retrying an uncertain post, or canceling one, while a previous send may still be in progress answers HTTP 409 with retry_wait: try again in a few minutes. Canceling a post the publishing service is about to send answers HTTP 409 with about_to_publish, and one the service still reports as scheduled well after its time answers overdue_at_provider: nothing is changed, and the post keeps following what the service reports.

Limits

  • 60 reads and 30 writes per minute per key
  • Daily limits by plan, counted in UTC. Publications count for the whole workspace, so all its keys share them. AI credits count per key, always within the workspace's daily AI credit limit:
    • Creator: 50 publications, 50 AI credits per key, 300 AI credits per workspace
    • Pro: 200 publications, 200 AI credits per key, 900 AI credits per workspace
    • Agency: 1,000 publications, 1,000 AI credits per key, 2,250 AI credits per workspace
  • Active key slots by plan:
    • Creator: 2
    • Pro: 5
    • Agency: 20

Continue with MCP or CLI. To see what each network's own API asks of you, read social media APIs compared; Ayrshare is the developer-only alternative.

Create your workspace, generate an API key in Settings → API, and connect your agent.

Start your 7-day trial