Conventions
Versioning and compatibility, requests and responses, representations, caching, pagination and limits.
One versioned HTTP API serves every client, the workbench included. One operation registry defines it, and the OpenAPI document, the server and the platform's own client are all generated from that registry, so the published contract is exactly what runs.
Versioning and compatibility
The major version is part of the path: /api/v1. A change that could break an existing client requires a new path version; every other change stays within the current one. The methodology is versioned separately, so a methodology release changes numbers without changing the contract.
Compatible within /api/v1 | Breaking |
|---|---|
| Adding an operation | Removing or renaming an operation, parameter or property |
| Adding an optional query parameter | Adding a required input, or accepting less input than before |
| Accepting more input values than before | Changing the type or meaning of a value |
| Adding a response property or enumeration value |
Response schemas are closed: they declare additionalProperties: false. A client that validates responses strictly can rely on every property it knows, and a new property arrives only with a new path version.
Requests
- Paths. Operations live under
/api/v1/intelligence. Percent-encode path parameters. - Credentials.
Authorization: Bearerwith an access token, or the host's session cookie from the same origin. See Authentication. - The lens. Lens-scoped operations take the lens as query parameters. See The lens.
- Bodies. The few operations with a body, such as saving a watchlist, take uncompressed
application/jsonof at most 65,536 bytes, checked before anything is parsed. - Correlation. Send
X-Request-Idwith 1 to 128 characters fromA-Z,a-z,0-9,.,_and-, and it is echoed; otherwise the server generates one. Every response carries it, and every problem repeats it asrequestId.
Responses
- Representation. Successful responses are
application/json; charset=utf-8.GET /briefandGET /dossiers/{id}also returntext/markdownwithformat=markdown. - Provenance. Lens-scoped read models state their
revision,lensandmethodology. See Reproducibility.
Caching and conditional reads
| Response | Cache-Control | Conditional reads |
|---|---|---|
| Published read models | private, no-cache | Strong ETag; If-None-Match answers 304 |
| The caller's own state: alerts with read state, the watchlist | private, no-store | If-None-Match answers 304 |
| Everything else, problems included | no-store | None |
The ETag is the quoted base64url SHA-256 of the body. Send it back as If-None-Match to revalidate a cached response without downloading it again.
Pagination
| Operation | Page size | Next page |
|---|---|---|
GET /objects | pageSize 1 to 200, default 50 | Send nextPageToken as pageToken until it is null |
GET /revisions | limit 1 to 200, default 50 | Send nextBefore as before until it is null |
Limits
- Observations.
GET /indicators/{id}/observationsrefuses a query that selects more than 50,000 observations; restrict it bysubject,fromandto. - Capacity. A read whose data is not yet cached, such as an earlier revision or an as-of date no one has read, waits for capacity and shares the work of identical concurrent requests. When too many wait, it answers
503 overloadedwithRetry-After: 5. Cached reads are never refused this way. - Watchlists. A caller watches at most 500 objects.
Personal state
GET /alerts returns the alerts of the lens with the caller's read state and unread count, for every object or with scope=watchlist. POST /alerts/read marks one alert read or unread, or every alert through a date read, in one atomic update, and returns the complete read state. GET, PUT and DELETE /watchlist read, add to and remove from the caller's watchlist. These operations change only the caller's own state; published knowledge is read-only.