Canonical schemas

Named schemas for objects that appear in multiple endpoints. Reference these definitions instead of inferring shapes from individual endpoint examples.

API conventions

Rules that apply uniformly across every endpoint. An agent or code generator can rely on these without inspecting individual endpoint documentation.

Field naming

All request body fields and response fields use camelCase (e.g. accountIds, scheduledFor, platformPostUrl). There are no snake_case or kebab-case fields in the REST API.

Date and time

All datetime fields are ISO 8601 strings in UTC with a Z suffix (e.g. "2026-06-01T14:00:00Z"). The API never returns Unix timestamps or locale-specific formats. Submitting a datetime without a timezone offset is rejected with 400 INVALID_DATE.

ID format

All IDs are cuid2 strings with a resource-type prefix:

IDs are case-sensitive. Never construct or mutate ID strings — treat them as opaque tokens.

Enum casing

Enum values follow a consistent rule based on context:

When the same field (e.g. platform) appears in both a REST response and a webhook payload, its casing differs. See PlatformResult for the concrete example.

Null vs. absent fields

Optional fields that have no value are returned as null, not omitted. A field listed in the schema will always be present in the response object — you do not need to check 'field' in obj separately.

Exception: fields marked undefined in BulkItemResult are genuinely absent when not applicable (e.g. postId is absent on failure, not null).

Pagination envelope

All list endpoints return the same pagination shape:

{
  "data": [ ... ],
  "pagination": {
    "has_more": true,
    "next_cursor": "cjld2cjxh0000qzrmn831i7rn",
    "limit": 20
  }
}

Pass cursor (not page or offset) to fetch the next page. When has_more is false, next_cursor is null. The TypeScript SDK’s listAll() and Go SDK’s ListAll() handle cursor iteration automatically.

Unknown fields

The API may add new optional fields to any response without a major version bump. Clients must ignore unknown fields rather than failing on them. This is the only change guaranteed not to be announced in advance.

Post

Returned by POST /v1/posts, GET /v1/posts/:id, PATCH /v1/posts/:id, and all post list/lifecycle endpoints.

PlatformResult

Each item in post.platforms[]. Present in REST responses (lowercase) and webhook payloads (UPPERCASE).

ThreadItem

Each item in post.threadPosts[] (X/Twitter only).

Media object

Each item in post.media[] and standalone media endpoint responses.

WebhookEnvelope

The outer wrapper for all webhook deliveries.

BulkItemResult

Each item in POST /v1/posts/bulk → results[].

Account

Returned by account list, get, connect callback, and test endpoints.

WebhookEndpoint

Returned by webhook create, get, and list endpoints.