Reference

API

The MonitOps API is authenticated and tenant-scoped, and every call is checked against the caller's role. This article describes the conventions shared by its endpoints; each deployment publishes an OpenAPI description of its routes.

How it works#

Authentication and scope#

The API authenticates a user session. The tenant and role come from the server-side session membership; a tenant selected in the browser is a request, not proof of membership. Tenant and role are checked on every call, in the same way they are checked on every query and copilot tool (see Roles and access).

Ingest credentials are separate from user sessions. A source credential authenticates only to the OTLP paths, and a browser session never authenticates to them (see OTLP endpoint). External identity tokens are not accepted as API credentials.

Request conventions#

Routes are under /api/v1. The API uses GET for reads and POST for changes.

GET /api/v1/alerts?state=firing&limit=50

Successful JSON reads include asOf, the time the data reflects.

Request identifier and errors#

Errors use one body shape with a correlation identifier. Quote the identifier when you ask about a specific request.

{
  "code": "invalid_request",
  "message": "…",
  "correlationId": "…"
}

Status	Meaning
`400`	The request is invalid
`401`	The identity is absent or has expired
`403`	Your role does not allow the operation
`404`	The item is missing or you cannot access it
`413`	The request is over a size limit
`429`	A rate limit was reached; retry after the interval the response gives
`503`	A dependency is unavailable

The size and rate limits exist in every deployment; their values are set per deployment.

Pagination#

Lists use keyset pagination with an opaque cursor.

Item	Value
Default page size	50
Maximum page size	200
`limit`	Optional page size, up to the maximum
`cursor`	Returned by the previous page; it conveys no authority

A cursor is bound to the filters of the list it came from. Filters and role are applied again on every page.

Bounded time windows#

Reads of time-series and log data are bounded. Historical log reads cover a window of at most 60 minutes (see Logs). Truncated or incomplete results are marked as such rather than presented as complete.

OpenAPI description#

Each deployment serves an OpenAPI description generated from the routes it runs, so the specification matches the API you call.

Limits and defaults#

Item	Value
List page size	50 by default, 200 at most
Historical log window	60 minutes
Request size and rate	Limited; values per deployment

Failure states#

State	What the caller sees
Not signed in	`401`
Role not permitted	`403`
Over a rate limit	`429` with an interval to wait
Dependency unavailable	`503`

Last updated October 2026

API