Skip to main content

REST API

This page covers the conventions that apply to every REST endpoint. Individual endpoints are documented on their own pages — see the endpoint map.

Requests​

  • All request bodies are application/json (the one exception: POST /v1/media/upload, which is multipart/form-data).
  • Query parameters are used for filtering and pagination on GET requests.
  • Path parameters (e.g. {id}) identify a specific resource.
  • Every request needs an Authorization: Bearer sx_live_... header — see Authentication.

The OpenAPI spec​

GET /api/openapi.json returns the full OpenAPI 3.1.0 specification (server base /api) with request and response schemas for every route. It is the most reliable way to introspect the API programmatically.

curl https://<your-api-origin>/api/openapi.json

Responses​

All responses are application/json.

  • Success envelope. Successful responses wrap the payload:

    { "data": { "id": "pst_abc123", "status": "scheduled" } }

    List endpoints return the array plus their paging echo inside data siblings — e.g. GET /v1/posts returns { "data": [...], "limit": 25, "offset": 0 }, and GET /v1/media and GET /v1/inbox return { "data": { "items": [...], "total": 42 } }.

  • Status depends on the operation. POST /v1/posts returns 201 Created. Starting a clipping job returns 202 Accepted; processing continues asynchronously. Other documented successful mutations normally return 200 OK. Check the endpoint reference.

  • Deletes return { "data": { "success": true } }.

Pagination​

Most list endpoints accept two query parameters:

ParameterTypeDefaultRange
limitinteger251–100 (media defaults to 24)
offsetinteger0≥ 0
curl "https://<your-api-origin>/api/v1/posts?limit=10&offset=20" \
  -H "Authorization: Bearer sx_live_YOUR_API_KEY"
{
  "data": [{ "id": "pst_abc123", "...": "..." }],
  "limit": 10,
  "offset": 20
}

Endpoints that don't paginate: GET /v1/accounts and GET /v1/comments return plain arrays inside data.

Validation​

Each route validates its input (query, body, or path params) against a schema before the handler runs. Invalid input short-circuits with 400 carrying a Zod-style error listing exactly which fields failed.

Handler-level validation errors use the structured shape:

{
  "error": {
    "code": "validation_error",
    "message": "Provide a `file` form field"
  }
}

Creating a post runs an additional layer of validation against platform limits — a 400 (constraint violation) or 403 (ownership/forbidden) is returned if the post would break a platform rule. See Errors for the complete catalog.

Versioning​

The API is versioned in the path (/v1/...). Breaking changes will ship under a new version; non-breaking additions (new fields, new endpoints) happen within v1.

Next​