Skip to content

API

The API reference is rendered from api/openapi.yaml, the OpenAPI 3.1 document that the binary serves at /api/v1/openapi.yaml, so it describes this version of Muster. In short:

  • Listeners. The API is served under /api/v1 on the app listener, next to the UI; ingestion, Heartbeats and messenger callbacks under /api/v1 on the ingest listener; the health checks and /metrics on the internal listener.
  • Authentication. The UI uses a session cookie, with the X-CSRF-Token header on every request that changes something. Scripts send a Personal access token (mstr_pat_) or a Service account token (mstr_sat_) as a bearer token. An Integration token (mstr_int_) is accepted only by ingestion and the Heartbeat.
  • Identifiers. URLs carry the public_id of a resource: a type prefix of one or two letters and 12 characters of Crockford base32, such as AGK7M3QX9P2RTA; never the #N of an Alert Group.
  • Pagination. Lists take cursor and limit (50 by default, at most 500), and a page carries next_cursor.
  • Errors. Errors are RFC 9457 problems (application/problem+json) with a stable type, a stable code where a refusal needs one, and errors[] with a JSON pointer per invalid field. An operation that this version does not implement yet answers 501.
  • Concurrency. A configuration resource carries an ETag; an update sends it in If-Match and gets 412 when it no longer matches, 428 without it.
  • Values. Times are RFC 3339 in UTC; durations are whole seconds in *_seconds, retention periods whole days in *_days and measured latencies milliseconds in *_ms; enums are snake_case. Secrets are write-only: a read shows only whether one is set and when it was last changed, in <field>_status.
  • Rate limits. 429 with Retry-After, per token; ingestion is not rate-limited.