Docs
API: authentication & errors
A read-only HTTP API over your own data, authenticated with a workspace key.
The public API is read-only. There are no POST, PUT or DELETE routes on
/api/v1 — writes happen through control actions, which
are a separate path with their own authorisation.
The API requires the Pro plan or above.
Authentication
Create a key under Settings → API. Keys begin with obsv_ and are shown once;
only a hash is stored.
GET /api/v1/runs HTTP/1.1
Host: app.obsevo.com
Authorization: Bearer obsv_…The workspace is derived from the key. There is no request shape that reaches another workspace's data, and no parameter for selecting one.
Entitlement is re-checked on every request, not just when the key is created — a key minted on a paid plan stops working if the workspace later downgrades or cancels.
Errors
Every error has the same body:
{ "error": "rate_limited", "message": "Too many requests." }| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | Missing, malformed, unknown or revoked key. |
| 402 | payment_required | The workspace plan does not include API access. |
| 404 | not_found | No such record in this workspace. |
| 429 | rate_limited | Over the per-key limit. See `retry-after`. |
| 500 | internal_error | Unhandled server error. Deliberately opaque. |
internal_error is deliberately opaque. An internal error message can carry SQL,
table names or connection details, so the specific cause stays in our logs.
Rate limiting
120 requests per minute per key. Exceeding it returns 429 with a
retry-after header in seconds.
The limit is per-replica and in-process rather than globally coordinated. It is
deliberately conservative rather than exact: the goal is to stop a runaway script
hammering the database, not to meter billing. A split-profile deployment running
several dashboard replicas will therefore allow proportionally more.
Next
- Query grammar and pagination — the filter syntax, shared with the runs explorer
- Endpoints