Requests and responses
The response envelope, headers, timestamps and caching rules shared by every partner endpoint.
Requests
- Use
GET. Partners only read: any other method answers405 Method not allowed. - Send the customer's key in
X-API-Keyand your secret inX-Partner-Secreton every request, from a registered address (Authentication). - Call from your servers only. The API does not enable cross-origin (CORS) requests.
- Responses are gzip-compressed when you send
Accept-Encoding: gzip. Most HTTP clients do this by default. - Timestamps are ISO 8601 in UTC, for example
2026-03-18T10:22:05.117Z. Columns that store only a date are serialized as midnight UTC. - Field names are Vitruve's own and are never renamed.
The envelope
Every response, success or error, has the same top level.
| Field | Type | Present | Description |
|---|---|---|---|
ok | boolean | always | true on success, false on any error. |
timestamp | number | always | Server time in Unix milliseconds. |
data | object or array | success | A single resource, or the items of a list. |
meta | object | lists | Pagination state. See Pagination. |
message | string | errors | Human-readable description of what went wrong. |
A single resource
{
"ok": true,
"timestamp": 1738247125207,
"data": { "id": "3b9c1e24-6f7a-4d2b-8c15-a40e9d7f1b62", "name": "Marta" }
}A list
{
"ok": true,
"timestamp": 1738247125207,
"data": [{ "id": "3b9c1e24-6f7a-4d2b-8c15-a40e9d7f1b62", "name": "Marta" }],
"meta": { "limit": 50, "hasMore": true, "nextCursor": "ZTU2M2ZlYzMtM2Ix…" }
}An error
{
"ok": false,
"timestamp": 1738247125207,
"message": "Invalid query parameters: 'limit': Number must be less than or equal to 100"
}Branch on the HTTP status and ok, not on the text of message. Messages are written for people and can be reworded. See Error codes.
Response headers
| Header | Meaning |
|---|---|
X-Request-Id | Unique id of the request. Include it when you contact support. |
RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset | The customer key's current rate-limit window, on every response past the authentication checks. See Rate limits. |
Retry-After | On 429 only: seconds to wait. |
Cache-Control: private, no-store | Responses contain one customer's private data. Do not cache them in shared caches. |
Nulls, missing fields and optional data
Nullable columns are returned as null, not omitted. A field you do not see in the reference is not part of the contract: ignore unknown fields so your integration keeps working when new ones appear.