Skip to content

Pagination & Versioning

Versioning

Every endpoint is namespaced under /v1. The version is part of the path, so a future /v2 can ship side-by-side without breaking existing clients.

https://api.telbox.ai/v1/...

We treat the following as backward-compatible within /v1 (your client should tolerate them without changes):

  • New endpoints, new optional request fields, new response fields.
  • New enum values and new event types on the WebSocket (treat unknown type as a no-op).
  • New optional query parameters.

Breaking changes — removing or renaming a field, changing a type, tightening validation — would land under a new version prefix.

The spec is the contract

The OpenAPI documents (full · public) are generated from the live application, so they are the authoritative shape. Diff them between releases to detect changes.

Pagination

Telbox list endpoints use time-window pagination, not opaque cursors. You page by passing a timestamp boundary plus a limit.

Messages

GET /v1/messages is the canonical example:

Param Type Default Notes
before ISO-8601 datetime — Return messages older than this (page backward).
after ISO-8601 datetime — Return messages newer than this (reconnect catch-up).
limit int 50 1–200.

Page backward (history): request a page, then pass the oldest returned timestamp as before on the next call:

# newest page
curl "https://api.telbox.ai/v1/messages?limit=50" -H "Authorization: Bearer $TOK"
# older page
curl "https://api.telbox.ai/v1/messages?before=2026-05-24T18:00:00Z&limit=50" \
  -H "Authorization: Bearer $TOK"

Catch up (realtime reconnect): after a dropped WebSocket, pass the last timestamp you saw as after:

curl "https://api.telbox.ai/v1/messages?after=2026-05-24T18:00:00Z" \
  -H "Authorization: Bearer $TOK"

Other list endpoints

  • Limits vary by endpoint — some default limit to 50 (max 200), others to 20 (max 100). Check the endpoint in the reference.
  • A few small, bounded lists (e.g. GET /v1/threads) return the full set with no pagination; filter with the documented query params instead.

No cursor parameter

There is no opaque cursor token anywhere in /v1. If you see one in a client library, it's a local abstraction over the before/after timestamps.