data and the bookkeeping from meta. You never have to special-case the parsing logic per endpoint.
This page describes the envelope, every meta field, and how the request identifier flows through both successful and error responses for tracing.
The two payload shapes
data is the only field whose type varies, and it varies in exactly one way:
- List responses put an array in
data. List responses are the ones that paginate, so theirmetacarries apaginationblock. - Item responses put a single object in
data. Item responses describe one resource (for example one country, one entity, or one provenance chain) and do not paginate.
meta block, the top-level requestId) is identical across both.
Only list responses include
meta.pagination. Item responses omit it because there is nothing to page through.Top-level fields
array | object
required
The response payload. An array for list endpoints, a single object for item endpoints. This is the only field whose type changes between response kinds.
object
required
Response metadata: the request identifier, the API version, and (on list responses) the pagination block. See below.
string
required
The request identifier, repeated at the top level for convenience. Identical to
meta.request_id and meta.requestId. Quote this value when you contact support.The meta block
string
required
A UUID that uniquely identifies this request on the server. Logged server-side, so it lets support trace exactly what your call did.
string
required
The same UUID as
meta.request_id, provided in camelCase as well so clients in either naming convention can read it without transformation.string
required
The API version that served the response. Always
"v1" for the current surface. Paths are versionless; this field reports the underlying API version.object
Present on list responses only. Carries the cursor state for paging through results. See the Pagination page for the full loop.
The request identifier
Both successful and error responses carry the same identifier in three places:meta.request_id, meta.requestId, and the top-level requestId. They always hold the same value within one response. The redundancy exists so you can read the identifier whether your code expects snake_case or camelCase, and whether it inspects the envelope root or the meta block.
Capture it on every response, including errors. It is the fastest way for support to find your request in the logs.
Capturing the request id (TypeScript)
Error responses
Errors use a sibling envelope:error replaces data, and the request identifier is preserved so failures stay traceable. See the Errors page for the full shape and the code table.
Error envelope
Pagination
Follow
next_cursor while has_more is true.Errors
The error envelope and the full code table.