Pagination and Error Conventions

This page documents the response conventions used by the APIContext REST API (v2 and v3).

Pagination

The APIContext API uses cursor-based pagination for list endpoints.

Request parameters

Parameter	Type	Description
page_size	integer	Number of items to return (default: varies by endpoint; max: 100)
cursor	string	Opaque cursor value from the previous response's meta.next_cursor

Response shape

All paginated list responses include a meta object:

{
  "data": [ ... ],
  "meta": {
    "more": true,
    "next_cursor": "eyJpZCI6MTIzfQ==",
    "total_count": 847
  }
}

Field	Type	Description
meta.more	boolean	true if there are additional pages; false when you have reached the last page
meta.next_cursor	string	Pass as the cursor query parameter in the next request. Present only when more is true.
meta.total_count	integer	Total number of items across all pages (where available)

Iterating all pages

cursor = None
while True:
    params = {"page_size": 100}
    if cursor:
        params["cursor"] = cursor
    resp = requests.get("/api/2/calls/", params=params, headers=headers)
    data = resp.json()
    process(data["data"])
    if not data["meta"]["more"]:
        break
    cursor = data["meta"]["next_cursor"]

Create responses

Successful PUT create requests return HTTP 201 Created (not 200) with the created object in the body.

Error shape

All error responses use a consistent JSON body:

{
  "error_msg": "Human-readable description of what went wrong",
  "error_code": "MACHINE_READABLE_CODE"
}

Field	Type	Description
error_msg	string	Human-readable explanation. Always present on error responses.
error_code	string	Machine-readable error identifier. Use this for programmatic error handling.

Common HTTP status codes

Code	Meaning
200	Success (for updates and reads)
201	Created (for PUT create operations)
400	Bad request — error_msg explains the validation failure
401	Unauthorized — API key missing or invalid
403	Forbidden — key is valid but lacks permission
404	Not found — resource does not exist
429	Rate limited — retry after the Retry-After header value
500	Server error — retry with exponential backoff

See also

• API Reference overview
• Using the APIContext API