API
Envelope and metadata
Every successful response is {data, meta}. data is the payload; meta says where it came from, what shaped it, and how to continue.
The envelope
Every 2xx JSON response has the same two keys:
{
"data": { "…": "the payload — its shape is on each reference page" },
"meta": { "caps": { "tier": "pro", "applied": [] }, "cursor": null }
}data is never reshaped by the envelope: a grid is a grid object, a list is an array. Errors use a different shape — see Errors.
What is in meta
| Field | Type | Meaning |
|---|---|---|
caps | object or null | Entitlement metadata on routes that check it: tier (the plan the request was served under) and applied (which caps shaped this response; empty means nothing was clamped). |
cursor | string or null | An opaque continuation cursor. Present only when there is another page — pass it back as ?cursor=. See Pagination. |
plane | string or null | Which serving tier answered (for example memory for live state, or cache). Useful when debugging latency; do not branch business logic on it. |
| endpoint context | varies | Each endpoint adds its own context — date, symbol, origin, expired_filtered, row_count and so on — documented on its reference page. |
Unknown meta fields will appear over time. Ignore the ones you do not use; the SDKs keep them for you.
The same metadata in headers
For clients that want it without parsing the body, the API also sends:
| Header | Meaning |
|---|---|
x-itm-plane | Same as meta.plane. |
x-itm-caps | The caps summary for the request. |
x-itm-extra | Endpoint-specific extras, when there are any. |
x-request-id | A unique id for the request. Quote it when you report a problem. |
ETag | On snapshot-style reads; see Caching. |
Browsers can read the first three from page script (the API lists them in Access-Control-Expose-Headers); x-request-id is visible to cURL and server-side clients.
SDK results
Both SDKs return a result that keeps the envelope intact: data, meta, the HTTP status, the request id and the ETag. Nothing in meta is dropped, including fields the SDK version does not know about.