API Reference

Authentication and permissions

Send Authorization: Bearer cvk_... on every API call. Create a key in Settings → API keys; only the workspace owner can create or revoke keys. A key belongs to one brand; request bodies cannot choose a different tenant. Pro permits one active key family; Studio permits five. Free and Starter do not include API access.

Creation grants select post, story, reel, email and ad independently. Existing keys retain their existing grants. The publishing grant is off by default. A key with publishing permission still needs the content:publish scope to use auto mode or approve, schedule or publish content. LinkedIn requires human review in the app, including when the key has publishing permission.

Keys created with the existing Settings controls start with all scopes. Use PATCH /key to remove scopes, restrict allowed_platforms, lower daily_token_limit, or set allow_auto_publish to false. The API cannot add authority. These reductions apply to every credential in the rotation family. Reads with the appropriate scope cover the brand; kind and destination restrictions apply to creation and mutations. Use separate brands for separate tenants.

Workflow and creation

1. Read GET /channels and GET /wallet.
2. Optionally call POST /content/validate with the creation body.
3. Call POST /content with a stable idempotency_key.
4. Poll GET /requests/{id} every few seconds, or subscribe to webhooks.
5. When generation finishes, retrieve each delivery's content_id with GET /content/{id}.
6. Edit or schedule eligible drafts through the API, or open their review_url in the app. Select the owning brand in the app first.

{
  "kind": "post",
  "brief": "Announce our new Thursday evening opening hours.",
  "platforms": ["ig", "fb"],
  "mode": "review",
  "idempotency_key": "hours-announcement-v1",
  "metadata": {"campaign": "autumn-hours"}
}

curl https://chaviar.app/api/v1/content \
  -H "Authorization: Bearer $CHAVIAR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"kind":"post","brief":"Announce our new Thursday evening opening hours.","mode":"review","idempotency_key":"hours-announcement-v1"}'

A new accepted request returns HTTP 202, an id, status composing, kind, mode and created_at. The Location header points to /api/v1/requests/{id}. Acceptance means queued, not generated or published.

Unknown fields are rejected. Channel selection is exact: an unavailable selected channel never broadens the request to other channels. Omitted platforms snapshot the connected, permitted channels at acceptance; key destination restrictions narrow this set. Reels choose the first eligible destination in the app's channel order. Channels connected later do not silently join an accepted request. A review request with no available destination can still generate downloadable content; an auto request with no available destination returns 409. Actual outputs and omitted channels appear in deliveries and skipped_platforms after generation.

Validation uses the same body, grants and destination rules. It returns cost, wallet affordability and currently available destinations. It does not fetch images, upload, reserve tokens, generate or publish. A valid result cannot guarantee later channel availability or model success.

Images and billing

The entire JSON body must fit within 20 MiB, including base64 expansion. Use public HTTP(S) image URLs for larger inputs. Each decoded/fetched input is capped at the configured upload limit (15 MiB by default) and normalized by the shared raster decoder. Supported raster formats include PNG, JPEG, WebP, HEIC/HEIF, AVIF, GIF, TIFF and BMP; SVG is not accepted. Image fetches validate every redirect and DNS address before connecting. Private-network URLs and credentialed URLs are refused.

A request pays for one creative, including its platform variants. Text-only caption edits are free. Regeneration creates a new review-mode request at the format's normal cost, preserving the original; it is not an in-place image or frame reroll. The regeneration endpoint requires a new brief and idempotency key. Frame-level editing and email layout editing remain in the app.

Generation failure or confirmed enqueue failure releases the reservation. Expiring/cancelling already-generated content and publishing failure do not refund successful generation. A network error or HTTP 500 is not proof that nothing was charged: retry with the same idempotency key and inspect the stored request. Interrupted jobs are reconciled without rerunning paid generation; already-produced content is linked, and confirmed stranded work is failed/refunded. Test brands may generate placeholders without tokens or live provider calls.

Requests and current status

GET /requests/{id} returns current truth across all platform cards. deliveries includes each content id, platform, generation/review/delivery status, timestamps, external id, safe error and action required. In-flight deliveries use the per-delivery status publishing. Partial publication may coexist with pending work or failures. Undoing approval can change scheduled back to awaiting_review.

complete means every delivery reached a terminal publication outcome (published, failed, expired or cancelled); a review-mode draft is ready to retrieve while complete is false. Omitted/unavailable destinations count as finished omissions; a partly published request can therefore be complete with skipped_platforms. To wait for generation, check the delivery generation_status fields rather than waiting for complete. Look at each delivery when a request is partially published. skipped_platforms reports requested channels without an output card; it is populated once content exists.

Deadlines and cancellation are checked when arming and again before provider send. A provider call already in flight may finish after cancellation/deadline; completed publications remain reported as published. Cancellation cannot retract a live post. The minute housekeeping process withdraws eligible siblings, even when another sibling already published.

Idempotency is scoped to the key family and survives rotation. Repeating a stored key returns HTTP 200 with the original request, even after publish_at has passed; a different body does not replace it. Replay uses read quota. Keep the same key for transport retries; use a different key for intentionally new work. Failed stored requests also replay their existing outcome.

Endpoint reference

All paths below are relative to /api/v1. List endpoints use limit (1–100, default 25) and an opaque cursor, returning data and next_cursor. Pass the returned cursor unchanged. Lists are newest first with stable id ordering within equal timestamps. Requests list is history across the brand; idempotency_key lookup is restricted to the calling key family.

For actions, send {"action":"schedule","publish_at":"2026-12-01T09:00:00Z"} using a future date within the permitted horizon. Approve chooses the normal brand slot; publish starts now. Cancellation disarms the individual card; restore returns it to review. A cancelled or expired request cannot be reactivated through a card action: create a fresh request. Uncertain provider sends return 409 and require verification in the app before any retry.

Content media URLs are signed for five minutes; fetch the content again for fresh URLs. URL can be null when media is unavailable. Library returns user-facing media only. Metrics are cached, may be missing, and carry their collection timestamps; reading never forces a provider refresh. Calendar follows the app's field names and includes items, coverage and meta. Channel connected means currently eligible for publishing; a paused or disconnected channel is false.

Key rotation and limits

Rotation returns plaintext once. Store the replacement before the old key's grace period ends. A second attempt to rotate the expiring predecessor returns 409; the plaintext cannot be recovered after a lost response. Revoke that family and create a replacement from Settings if necessary. Rotation shares capacity, quotas, idempotency and token accounting with its predecessor. Revoking any family member in Settings revokes the family. Queued work is governed by its accepted request; cancelling a request is how to stop it.

Validation uses read quota. Mutations use write quota. A daily_token_limit additionally caps net API creative token usage over a rolling 24-hour window for the family; rotation cannot reset it. Rate-limit responses include Retry-After. Limiters and accepted request state are shared across web replicas.

Webhook delivery

Create up to five subscriptions per brand with a public HTTPS URL. Subscriptions receive request.updated snapshots while enabled. A minute worker observes state changes; rapid intermediate transitions can coalesce into the latest snapshot. Each event contains id, type, created_at, request_id, monotonically increasing request version and data (the request representation). Existing requests may produce an initial snapshot after subscribing.

Delivery is at least once. Persist the event id and ignore duplicates. Request versions let consumers discard stale/out-of-order snapshots. Responses with a 2xx status acknowledge the event; redirects are refused. Network errors, oversized responses and other statuses retry, up to eight attempts with exponential delays starting at 30 seconds; the minute poll determines actual delivery time. Disabled subscriptions pause pending delivery. Successful deliveries cannot be manually replayed; undelivered idle ones can. Keep handlers quick: requests time out after ten seconds and responses are capped at 64 KiB.

The Chaviar-Event-Id header contains the stable event id. Chaviar-Signature is t=<unix-seconds>,v1=<hex-hmac>. Verify HMAC-SHA256 using the secret and exactly timestamp + "." + raw_request_body. Compare signatures in constant time, reject stale timestamps (for example outside five minutes), then parse JSON and process/deduplicate the event. Every attempt gets a fresh timestamp/signature but keeps the event id. The example client includes a verification helper. Store secrets securely; list endpoints never reveal them.

Errors and retry handling

Errors use {"error":{"code":"...","message":"..."}}. Responses include X-Request-Id and Cache-Control: no-store. Branch on error.code, not the text. An error can include a request_id referring to accepted work; the X-Request-Id is the HTTP correlation id.

Generation/request outcomes use sanitized codes such as generation_failed, content_blocked, publish_failed, schedule_failed, interrupted, enqueue_failed, invalid_image, insufficient_tokens, budget_exceeded and nothing_to_generate. Raw provider errors, prompts, credentials, storage keys and infrastructure costs are not part of this API. Treat future additional fields, statuses and error codes defensively.