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).
| Method | Path | Scope(s) | Class |
|---|---|---|---|
| GET | /whoami | key required | R |
| GET | /brands | brands:read | R |
| GET | /accounts | brands:read | R |
| GET | /posts | posts:read | R |
| GET | /posts/{postId} | posts:read | R |
| POST | /posts | posts:write | W |
| POST | /posts/{postId}/schedule | posts:write | W* |
| POST | /posts/{postId}/publish | posts:write | D |
| POST | /posts/{postId}/cancel | posts:write | D |
| POST | /ai/draft | ai:write | W |
| POST | /ai/adapt | ai:write | W |
* 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:
| HTTP | Code | Meaning |
|---|---|---|
| 400 | BAD_REQUEST | Invalid request payload |
| 401 | UNAUTHORIZED | Missing/invalid/revoked key |
| 402 | PAYMENT_REQUIRED | Inactive subscription required by paywall |
| 403 | FORBIDDEN | Scope or role does not allow this action |
| 404 | NOT_FOUND | Resource does not exist in this workspace |
| 409 | CONFLICT | State conflict (idempotency/version) |
| 429 | TOO_MANY_REQUESTS | Rate/day budget exceeded |
| 500 | INTERNAL_SERVER_ERROR | Unexpected server error |
| 503 | SERVICE_UNAVAILABLE | Temporary capacity issue (Retry-After: 1) |
For these validation failures, HTTP 400 uses BAD_REQUEST as the code and the reason below as the message:
| Message | Meaning |
|---|---|
account_disconnected | A selected account is unavailable or disconnected. |
plan_capacity_exceeded | The connected channel count exceeds the plan limit. |
gbp_location_required | The Google Business Profile account needs a location. |
gbp_invalid_media | The Google Business Profile media is invalid. |
destination_required | Choose a LinkedIn or Facebook destination first. |
destination_unknown | That destination is not selected for the account. |
Other validation failures use a specific code and a descriptive message:
| Code | Meaning |
|---|---|
instagram_media_required | Instagram needs an image or video. |
character_limit | The text exceeds a network's character limit. |
telegram_caption_limit | The Telegram caption exceeds its media limit. |
media_not_uploaded | Upload 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