Skip to main content

REST API

This page covers the conventions that apply to every REST endpoint. Individual endpoints are documented under Endpoints.

Requests​

  • All request bodies are application/json. Set Content-Type: application/json.
  • Query parameters are used for filtering and pagination on GET requests.
  • Path parameters (e.g. :id) identify a specific resource.

Responses​

  • All responses are application/json.
  • Successful list responses are wrapped: { "data": [...], "limit", "offset" }.
  • Successful create responses return the new resource (or its id/status) with HTTP 201.
  • Successful delete responses return { "success": true }.
  • Errors follow a consistent shape — see Errors.

Pagination​

List endpoints accept two query parameters:

ParameterTypeDefaultRange
limitinteger251–100
offsetinteger0≥ 0
curl "https://<your-api-origin>/api/v1/posts?limit=10&offset=20" \
  -H "Authorization: Bearer gx_live_YOUR_API_KEY"
{
  "data": [
    /* ...up to 10 posts... */
  ],
  "limit": 10,
  "offset": 20
}

Validation​

Each route validates its input (query, body, or path params) against a schema before the handler runs. Invalid input short-circuits with 400 and a details array describing exactly what failed:

{
  "error": "Invalid request",
  "details": [{ "path": ["accountIds"], "message": "Required" }]
}

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.

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.

Endpoints​

  • Posts — list, create, delete
  • Accounts — list connected accounts
  • Media — upload flow

Next​