Docs
Conventions

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/v1Breaking
Adding an operationRemoving or renaming an operation, parameter or property
Adding an optional query parameterAdding a required input, or accepting less input than before
Accepting more input values than beforeChanging 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: Bearer with 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/json of at most 65,536 bytes, checked before anything is parsed.
  • Correlation. Send X-Request-Id with 1 to 128 characters from A-Z, a-z, 0-9, ., _ and -, and it is echoed; otherwise the server generates one. Every response carries it, and every problem repeats it as requestId.

Responses

  • Representation. Successful responses are application/json; charset=utf-8. GET /brief and GET /dossiers/{id} also return text/markdown with format=markdown.
  • Provenance. Lens-scoped read models state their revision, lens and methodology. See Reproducibility.

Caching and conditional reads

ResponseCache-ControlConditional reads
Published read modelsprivate, no-cacheStrong ETag; If-None-Match answers 304
The caller's own state: alerts with read state, the watchlistprivate, no-storeIf-None-Match answers 304
Everything else, problems includedno-storeNone

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

OperationPage sizeNext page
GET /objectspageSize 1 to 200, default 50Send nextPageToken as pageToken until it is null
GET /revisionslimit 1 to 200, default 50Send nextBefore as before until it is null

Limits

  • Observations. GET /indicators/{id}/observations refuses a query that selects more than 50,000 observations; restrict it by subject, from and to.
  • 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 overloaded with Retry-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.