API docs by Redocly

Muster API (0.1.0)

Download OpenAPI specification:

License: AGPL-3.0-only

Muster L1 API

Spec-first contract of Muster L1: alert grouping and on-call after Alertmanager.

Listeners. Operations are served by one of three listeners, marked x-listener: app (UI and API, the default server), ingest (ingestion, Heartbeat, messenger callbacks; the address for machines) and internal (health and metrics). When two listeners share an address, both are served on that one port.

Permissions. Every operation lists the Permission it needs in x-permission (<resource>:<verb>; see the Permission schema for the Role matrix), or one of authenticated (any signed-in identity), integration-token or none. A Personal access token can only narrow its owner's Permissions.

Credentials. Operations that change the caller's own account (profile, password, TOTP, Personal access tokens, Account links, sessions) accept the web session with its CSRF token only; a token gets 403 (session_required). Service account tokens get 403 (service_account_not_allowed) on the reads under /me.

Conventions. Resources are plural kebab-case nouns and URLs use the opaque public_id. Lists use cursor pagination (cursor, limit default 50, maximum 500; the response carries next_cursor) and filters as query parameters. Errors are RFC 9457 application/problem+json (Problem; the stable codes are catalogued in x-problem-codes). An operation that this build does not implement yet answers 501 (not-implemented). Configuration resources return an ETag header and an etag field; updates are PUT with If-Match and fail with 412 on a mismatch, 428 without it. On an update an omitted optional field keeps its stored value and an explicit null clears it. A natural-key conflict is 409. Rate limits answer 429 with Retry-After. Times are RFC 3339 in UTC; durations are integer seconds in fields named *_seconds (retention periods are whole days in *_days, measured latencies are milliseconds in *_ms). Enum values are snake_case; kebab-case is kept for URL segments, problem types and the type of live-update hints. Secret fields are write-only; reads show *_status objects with set and updated_at.

Not validated by the spec. The ingestion endpoints accept any body up to the size limit and store it as received; they are excluded from request validation (see ingestSnapshot).

During 0.x breaking changes are allowed; from 1.0 /api/v1 is stable and a removal is announced one minor release in advance.

Sessions

Sign in with a local account or OIDC, the second factor, sessions, password setup. Public sign-in operations need no credentials. A session can be limited: while state is totp_required or totp_enrolment_required only the operations named in Session work; others answer 403 with the same code.

Read sign-in options

Whether the sign-in page shows the OIDC button next to the local form. Local sign-in is always available; no setting turns it off. Carries no version or other detail about the installation.

Responses

Response samples

Content type
application/json
{
  • "oidc": {
    }
}

Sign in with a local account

Creates a session cookie (HttpOnly; Secure; SameSite=Lax) and returns the CSRF token. If the user has TOTP and the request carries neither totp_code nor recovery_code, the session starts in the state totp_required and POST /sessions/current/totp completes it. Under a TOTP policy that covers a user without TOTP the state is totp_enrolment_required. A wrong login, password or code is 401 (invalid_credentials) without saying which one was wrong. Failed attempts slow down per account and per source address (429 with Retry-After). A request a browser marks as cross-site (Sec-Fetch-Site set to cross-site) is refused with 403 (csrf_invalid).

Request Body schema: application/json
required
login
required
string

Compared case-insensitively.

password
required
string <password>
totp_code
string

Current TOTP code, if the user has TOTP and wants to finish in one request.

recovery_code
string

A single-use recovery code instead of totp_code.

Responses

Request samples

Content type
application/json
{
  • "login": "string",
  • "password": "pa$$word",
  • "totp_code": "string",
  • "recovery_code": "string"
}

Response samples

Content type
application/json
{
  • "user": {
    },
  • "state": "active",
  • "csrf_token": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "idle_expires_at": "2019-08-24T14:15:22Z",
  • "method": "local",
  • "permissions": [
    ]
}

Read the current session

Returns the session in any state, including the CSRF token the SPA sends on mutating requests.

Authorizations:
sessionCookie

Responses

Response samples

Content type
application/json
{
  • "user": {
    },
  • "state": "active",
  • "csrf_token": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "idle_expires_at": "2019-08-24T14:15:22Z",
  • "method": "local",
  • "permissions": [
    ]
}

Sign out

Ends the session, in any state.

Authorizations:
(sessionCookiecsrf)

Responses

Response samples

Content type
application/problem+json
Example
{}

Give the second factor

Completes a session in the state totp_required with a current TOTP code or a single-use recovery code; works the same after a local and an OIDC sign-in. A wrong code is 401 (invalid_credentials) and slows down like a wrong password; 409 (totp_not_pending) when the session is not waiting for a code.

Authorizations:
(sessionCookiecsrf)
Request Body schema: application/json
required
= 1 properties
totp_code
string

Current TOTP code.

recovery_code
string

A single-use recovery code.

Responses

Request samples

Content type
application/json
{
  • "totp_code": "string"
}

Response samples

Content type
application/json
{
  • "user": {
    },
  • "state": "active",
  • "csrf_token": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "idle_expires_at": "2019-08-24T14:15:22Z",
  • "method": "local",
  • "permissions": [
    ]
}

Start OIDC sign-in

Redirects the browser to the identity provider with PKCE (S256), state and nonce, all mandatory, requesting offline_access besides the configured scopes; when the IdP grants it, the offline token is stored on the user, encrypted, replacing the previous one. Muster exchanges the code itself through the back channel. The redirect URI to register at the identity provider is MUSTER_PUBLIC_URL/api/v1/sessions/oidc/callback. 409 (oidc_not_enabled) while OIDC is off.

query Parameters
return_to
string

Path to open after sign-in: a relative path that starts with a single / (never //, /\ or a scheme), at most 2000 characters. Anything else is ignored, not refused, so the flow is no open redirect.

Responses

Response samples

Content type
application/problem+json
Example
{
  • "type": "https://muster-io.github.io/muster/problems/command-refused",
  • "title": "Command refused",
  • "status": 409,
  • "detail": "A newer open Alert Group #415 exists.",
  • "instance": "/api/v1/alert-groups/AGK7M3QX9P2RTA/unresolve",
  • "code": "newer_alert_group_exists",
  • "related_alert_group": {
    }
}

Complete OIDC sign-in

Redirect target of the identity provider. Every outcome is a 302 to the SPA, so the browser never shows a raw error. On success it sets the session cookie (state active, or totp_required when the user has TOTP and the identity provider did not assert multi-factor authentication) and redirects to the return_to of the start or to /. The first sign-in of a new identity creates the user, with the login taken from preferred_username, else the email, else sub. Accounts are never merged by login or email; an identity reaches an existing account only by linking it from that account's profile (startOidcLink). A failure redirects to /sign-in?error=<code> with one of no_access (the person is in no mapped group; the Audit log records the groups from the claim), login_taken (a new identity's login belongs to an existing account; the page says "An account with this login already exists. Sign in with it and link OIDC in your profile.", and the Audit log records the refusal), account_disabled, oidc_disabled, invalid_request (bad or missing state, code or nonce) and idp_error (the identity provider or the back channel failed).

query Parameters
code
string

Authorization code.

state
string

State issued by startOidcSignIn.

error
string

Error reported by the identity provider.

Responses

Response samples

Content type
application/problem+json
{}

Set a password from a setup link

Uses the single-use token of a password setup link (the link carries it in the URL fragment, so it reaches neither server logs nor referrers). The user is then asked to enrol TOTP if the policy requires it. An unknown token is 404; a token past auth.password_setup_link_ttl is 410 (link_expired); one already used or replaced by a newer link is 410 (link_used). Like the sign-in, a request that a browser marks as cross-site is 403 (csrf_invalid).

Request Body schema: application/json
required
token
required
string

The token from the setup link.

password
required
string <password>

At least auth.password_min_length characters; a shorter one gets 422 with too_short.

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "password": "pa$$word"
}

Response samples

Content type
application/problem+json
{}

Profile

The caller's own profile, password, sessions and TOTP.

Read own profile

The caller and the effective Permissions, narrowed by the token if one is used. Service account tokens get 403 (service_account_not_allowed).

Authorizations:
sessionCookieapiToken

Responses

Response samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Update own profile

Changes name, time zone and language. Web session only.

Authorizations:
(sessionCookiecsrf)
Request Body schema: application/json
required
name
required
string non-empty
time_zone
string or null
language
string or null (NullableLanguage)
Enum: "en" "ru" null

UI or template language; null follows the default.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "time_zone": "string",
  • "language": "en"
}

Response samples

Content type
application/json
{
  • "user": {
    },
  • "permissions": [
    ]
}

Change own password

Ends all other sessions of the user. Local users only (409 local_user_only otherwise). Web session only.

Authorizations:
(sessionCookiecsrf)
Request Body schema: application/json
required
current_password
required
string <password>
new_password
required
string <password>

At least auth.password_min_length characters; a shorter one gets 422 with too_short.

Responses

Request samples

Content type
application/json
{
  • "current_password": "pa$$word",
  • "new_password": "pa$$word"
}

Response samples

Content type
application/problem+json
{}

List own sessions

Sessions of the user, the current one marked.

Authorizations:
sessionCookie

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Sign out everywhere

Ends every session of the user, the current one included. Web session only.

Authorizations:
(sessionCookiecsrf)

Responses

Response samples

Content type
application/problem+json
Example
{}

Read own TOTP status

Whether TOTP is enrolled, a first code is awaited, and how many recovery codes remain. Service account tokens get 403 (service_account_not_allowed).

Authorizations:
sessionCookieapiToken

Responses

Response samples

Content type
application/json
{
  • "enrolled": true,
  • "enrolled_at": "2019-08-24T14:15:22Z",
  • "enrolment_pending": true,
  • "recovery_codes_remaining": 0
}

Begin TOTP enrolment

Returns the seed and the otpauth URI once. Enrolment completes when confirmTotpEnrolment receives a first code. Allowed in the session state totp_enrolment_required. 409 (totp_already_enrolled) when TOTP is already on. Web session only.

Authorizations:
(sessionCookiecsrf)

Responses

Response samples

Content type
application/json
{
  • "secret": "string",
  • "otpauth_uri": "string"
}

Remove own TOTP

Needs proof that the person is at the keyboard: the current password (local users) or a current TOTP or recovery code. Under a TOTP policy that covers the user, the next sign-in demands enrolment again. A wrong proof is 401 (invalid_credentials). Web session only.

Authorizations:
(sessionCookiecsrf)
Request Body schema: application/json
required
non-empty
password
string <password>

The current password; local users only.

totp_code
string

Current TOTP code.

recovery_code
string

A single-use recovery code.

Responses

Request samples

Content type
application/json
{
  • "password": "pa$$word",
  • "totp_code": "string",
  • "recovery_code": "string"
}

Response samples

Content type
application/problem+json
{}

Confirm TOTP enrolment

Confirms with a first code and issues auth.totp_recovery_codes single-use recovery codes, shown once. Allowed in the session state totp_enrolment_required. 409 (totp_enrolment_not_started) without a begun enrolment, totp_already_enrolled if already confirmed. Web session only.

Authorizations:
(sessionCookiecsrf)
Request Body schema: application/json
required
code
required
string

Current TOTP code.

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "codes": [
    ]
}

Regenerate recovery codes

Invalidates the previous codes. Requires a current TOTP code. Web session only.

Authorizations:
(sessionCookiecsrf)
Request Body schema: application/json
required
code
required
string

Current TOTP code.

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "codes": [
    ]
}

Users

Users and Roles. Admin only.

List users

Authorizations:
sessionCookieapiToken
query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

q
string

Case-insensitive match on name, login and email.

role
string (RoleName)
Enum: "admin" "responder" "viewer"

Filter by Role.

status
string (UserStatus)
Enum: "active" "disabled" "deleted"

Filter by status.

source
string (UserSource)
Enum: "local" "oidc" "bootstrap"

Filter by source.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Create a local user

Returns a single-use password setup link; Muster sends no email. A token may only assign a Role whose Permissions it holds itself (422 permission_not_held at /role).

Authorizations:
(sessionCookiecsrf) apiToken
Request Body schema: application/json
required
name
required
string non-empty
login
required
string non-empty

Stored as entered and unique case-insensitively in the Organization (409 name_taken when another user has the same login in any case).

email
string or null
role
required
string (RoleName)
Enum: "admin" "responder" "viewer"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "login": "string",
  • "email": "string",
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "user": {
    },
  • "password_setup_link": {}
}

Read a user

Authorizations:
sessionCookieapiToken
path Parameters
user_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

User public_id.

Responses

Response samples

Content type
application/json
{
  • "id": "AGK7M3QX9P2RTA",
  • "name": "string",
  • "login": "string",
  • "email": "string",
  • "role": "admin",
  • "role_locked": true,
  • "source": "local",
  • "oidc_offline_access": true,
  • "sign_in_method": "local",
  • "status": "active",
  • "totp_enabled": true,
  • "time_zone": "string",
  • "language": "en",
  • "last_sign_in_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Update a user

Changes name, email and Role. A Role change ends the user's sessions. Refused with 409 (role_locked) for a Role change of an account that signs in through OIDC while OIDC and oidc.sync_role are both on, and with 409 (last_admin) when it would give the last active Admin a lower Role. A token may only assign a Role whose Permissions it holds itself (422 permission_not_held at /role).

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
user_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

User public_id.

header Parameters
If-Match
required
string

ETag of the representation being replaced, as returned by the last read. A mismatch gets 412; a missing header gets 428.

Request Body schema: application/json
required
name
required
string non-empty
email
string or null
role
required
string (RoleName)
Enum: "admin" "responder" "viewer"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "email": "string",
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "id": "AGK7M3QX9P2RTA",
  • "name": "string",
  • "login": "string",
  • "email": "string",
  • "role": "admin",
  • "role_locked": true,
  • "source": "local",
  • "oidc_offline_access": true,
  • "sign_in_method": "local",
  • "status": "active",
  • "totp_enabled": true,
  • "time_zone": "string",
  • "language": "en",
  • "last_sign_in_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Delete a user

Deactivates and pseudonymizes: the name becomes deleted-user-<id>, the email is erased, sessions end, tokens are revoked and Account links are removed. Every acknowledged Alert Group the user owns becomes firing without an Owner, with an unacknowledged Timeline entry by the system and the reason owner_deleted. Audit log rows are never changed. The last active Admin cannot be deleted (409 last_admin).

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
user_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

User public_id.

header Parameters
If-Match
string

Optional ETag; when present and stale, the request gets 412.

Responses

Response samples

Content type
application/problem+json
Example
{}

Disable a user

Ends the user's sessions; tokens stop working until the user is enabled again. Every acknowledged Alert Group the user owns becomes firing without an Owner, with an unacknowledged Timeline entry by the system and the reason owner_disabled; enabling the user again gives no acknowledgement back. The last active Admin cannot be disabled (409 last_admin).

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
user_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

User public_id.

Responses

Response samples

Content type
application/json
{
  • "id": "AGK7M3QX9P2RTA",
  • "name": "string",
  • "login": "string",
  • "email": "string",
  • "role": "admin",
  • "role_locked": true,
  • "source": "local",
  • "oidc_offline_access": true,
  • "sign_in_method": "local",
  • "status": "active",
  • "totp_enabled": true,
  • "time_zone": "string",
  • "language": "en",
  • "last_sign_in_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Enable a user

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
user_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

User public_id.

Responses

Response samples

Content type
application/json
{
  • "id": "AGK7M3QX9P2RTA",
  • "name": "string",
  • "login": "string",
  • "email": "string",
  • "role": "admin",
  • "role_locked": true,
  • "source": "local",
  • "oidc_offline_access": true,
  • "sign_in_method": "local",
  • "status": "active",
  • "totp_enabled": true,
  • "time_zone": "string",
  • "language": "en",
  • "last_sign_in_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Reset a user's TOTP

Audited. The user enrols again at the next sign-in if the policy requires it.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
user_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

User public_id.

Responses

Response samples

Content type
application/problem+json
Example
{}

Convert an OIDC account to local

Removes the OIDC identity of an account that signs in through OIDC — created through OIDC or linked — and ends its sessions; the response carries a password setup link, as at user creation, and the Audit log records the conversion. The account keeps its TOTP enrolment and, once the password is set, signs in only with it. 409 with oidc_not_linked when the account does not sign in through OIDC.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
user_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

User public_id.

Responses

Response samples

Content type
application/json
{
  • "user": {
    },
  • "password_setup_link": {}
}

List users for pickers and filters

Name, login and whether the user is deactivated, for the Owner filter, Mention settings and other pickers. Includes deleted users, because their acknowledgements stay visible. Available to everyone who reads Alert Groups, unlike listUsers.

Authorizations:
sessionCookieapiToken
query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

q
string

Case-insensitive match on name and login.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

List Roles with their Permissions

Authorizations:
sessionCookieapiToken

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

OIDC

OIDC settings and the connection check.

Read OIDC settings

The client secret is never returned; client_secret_status shows whether it is set and when it changed.

Authorizations:
sessionCookieapiToken

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "display_name": "string",
  • "issuer_url": "http://example.com",
  • "client_id": "string",
  • "client_secret_expires_on": "2019-08-24",
  • "scopes": [
    ],
  • "groups_claim": "string",
  • "group_mappings": [
    ],
  • "unmatched_role": "none",
  • "sync_role": true,
  • "skip_totp_with_idp_mfa": true,
  • "client_secret_status": {
    },
  • "proxy": {
    },
  • "warnings": [
    ],
  • "updated_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Update OIDC settings

Replaces the writable fields; omitted optional fields keep their value. Saving with an empty mapping and no Role for unmatched users returns the warning nobody_can_sign_in in the result. The Audit log diff shows only that the client secret changed.

Authorizations:
(sessionCookiecsrf) apiToken
header Parameters
If-Match
required
string

ETag of the representation being replaced, as returned by the last read. A mismatch gets 412; a missing header gets 428.

Request Body schema: application/json
required
enabled
required
boolean
display_name
string

Provider name for the button "Sign in with {display_name}". Defaults to the host of the issuer URL; a read leaves it out while the default applies, and an empty value returns to the default.

issuer_url
required
string <uri>
client_id
required
string
client_secret_expires_on
string or null <date>

Optional expiry date of the client secret; the OIDC settings warn within oidc.secret_expiry_lead.

scopes
Array of strings

Scopes requested at sign-in and linking. Muster always adds openid and offline_access; allow offline_access for the Muster client at the IdP, or users are not re-checked in the background, OIDC sessions end after auth.oidc_fallback_session_lifetime, and Personal access tokens follow auth.oidc_token_grace.

groups_claim
required
string
required
Array of objects (OidcGroupMapping)
unmatched_role
required
string (OidcUnmatchedRole)
Enum: "none" "viewer" "responder"

Role for users without a matching group; none refuses the sign-in.

sync_role
required
boolean

On: the identity provider decides the Role at every sign-in. Off: the mapping applies only when the user is created.

skip_totp_with_idp_mfa
required
boolean
client_secret
string <password>

Write-only Secret. Omit to keep the stored one.

required
object (ProxyConfigInput)

Per-client proxy as written. Omitting password keeps the stored one; null clears it.

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "display_name": "string",
  • "issuer_url": "http://example.com",
  • "client_id": "string",
  • "client_secret_expires_on": "2019-08-24",
  • "scopes": [
    ],
  • "groups_claim": "string",
  • "group_mappings": [
    ],
  • "unmatched_role": "none",
  • "sync_role": true,
  • "skip_totp_with_idp_mfa": true,
  • "client_secret": "pa$$word",
  • "proxy": {
    }
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "display_name": "string",
  • "issuer_url": "http://example.com",
  • "client_id": "string",
  • "client_secret_expires_on": "2019-08-24",
  • "scopes": [
    ],
  • "groups_claim": "string",
  • "group_mappings": [
    ],
  • "unmatched_role": "none",
  • "sync_role": true,
  • "skip_totp_with_idp_mfa": true,
  • "client_secret_status": {
    },
  • "proxy": {
    },
  • "warnings": [
    ],
  • "updated_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Check the connection to the identity provider

Fetches discovery through the outbound HTTP package, with the saved proxy, and reports whether the groups claim is advertised (warning groups_claim_missing).

Authorizations:
(sessionCookiecsrf) apiToken

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "via": "direct",
  • "latency_ms": 0,
  • "issuer": "string",
  • "authorization_endpoint": "string",
  • "token_endpoint": "string",
  • "jwks_uri": "string",
  • "error": "string",
  • "warnings": [
    ]
}

Audit log

The append-only record of who changed or did what.

List Audit log entries

Newest first. The log is append-only; configuration changes carry a before/after diff in which Secrets only show that they changed.

Authorizations:
sessionCookieapiToken
query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

from
string <date-time>

Start of the time range (RFC 3339, UTC).

to
string <date-time>

End of the time range (RFC 3339, UTC).

actor
string

Actor public_id (user or Service account).

action
string

Action type, for example integration.update.

resource_type
string

Resource type, for example integration.

resource_id
string

Resource public_id.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

API tokens

Personal access tokens and Service accounts with their tokens.

List own Personal access tokens

Values are never returned. Each token shows when and from which address it was last used. Service account tokens get 403 (service_account_not_allowed).

Authorizations:
sessionCookieapiToken

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a Personal access token

Shows the token once. Its Permissions must be a subset of the Permissions the caller holds now (422 permission_not_held on /permissions/<i>). Web session only: a token can never mint another token.

Authorizations:
(sessionCookiecsrf)
Request Body schema: application/json
required
name
required
string non-empty
permissions
required
Array of strings (Permission) non-empty
Items Enum: "alert-groups:read" "alert-groups:acknowledge" "alert-groups:resolve" "alert-groups:snooze" "alert-groups:note" "alerts:read" "integrations:read" "integrations:write" "stored-snapshots:read" "routes:read" "routes:write" "connections:read" "connections:write" "destinations:read" "destinations:write" "destinations:test" "link-rules:read" "link-rules:write" "lookup-tables:read" "lookup-tables:write" "templates:preview" "users:read" "users:write" "oidc:read" "oidc:write" "service-accounts:read" "service-accounts:write" "organization:write" "organization:read" "audit-log:read" "system-status:read"

Must be a subset of the Permissions the caller holds.

expires_at
string or null <date-time>

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "permissions": [
    ],
  • "expires_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "token": {
    },
  • "value": "string"
}

Revoke a Personal access token

Revokes the token at once. Web session only.

Authorizations:
(sessionCookiecsrf)
path Parameters
token_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Token id.

Responses

Response samples

Content type
application/problem+json
Example
{}

List Service accounts

Authorizations:
sessionCookieapiToken
query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Create a Service account

A token may only assign a Role whose Permissions it holds itself (422 permission_not_held at /role).

Authorizations:
(sessionCookiecsrf) apiToken
Request Body schema: application/json
required
name
required
string non-empty
role
required
string (RoleName)
Enum: "admin" "responder" "viewer"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "id": "AGK7M3QX9P2RTA",
  • "name": "string",
  • "role": "admin",
  • "status": "active",
  • "token_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Read a Service account

Authorizations:
sessionCookieapiToken
path Parameters
service_account_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Service account public_id.

Responses

Response samples

Content type
application/json
{
  • "id": "AGK7M3QX9P2RTA",
  • "name": "string",
  • "role": "admin",
  • "status": "active",
  • "token_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Update a Service account

A token may only assign a Role whose Permissions it holds itself (422 permission_not_held at /role).

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
service_account_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Service account public_id.

header Parameters
If-Match
required
string

ETag of the representation being replaced, as returned by the last read. A mismatch gets 412; a missing header gets 428.

Request Body schema: application/json
required
name
required
string non-empty
role
required
string (RoleName)
Enum: "admin" "responder" "viewer"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "id": "AGK7M3QX9P2RTA",
  • "name": "string",
  • "role": "admin",
  • "status": "active",
  • "token_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Delete a Service account

Revokes its tokens.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
service_account_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Service account public_id.

header Parameters
If-Match
string

Optional ETag; when present and stale, the request gets 412.

Responses

Response samples

Content type
application/problem+json
Example
{}

Disable a Service account

Its tokens stop working until the account is enabled again.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
service_account_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Service account public_id.

Responses

Response samples

Content type
application/json
{
  • "id": "AGK7M3QX9P2RTA",
  • "name": "string",
  • "role": "admin",
  • "status": "active",
  • "token_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Enable a Service account

Makes a disabled Service account usable again; its tokens work again.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
service_account_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Service account public_id.

Responses

Response samples

Content type
application/json
{
  • "id": "AGK7M3QX9P2RTA",
  • "name": "string",
  • "role": "admin",
  • "status": "active",
  • "token_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

List tokens of a Service account

Authorizations:
sessionCookieapiToken
path Parameters
service_account_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Service account public_id.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a Service account token

Shows the token once. Web session only: a token can never mint another token.

Authorizations:
(sessionCookiecsrf)
path Parameters
service_account_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Service account public_id.

Request Body schema: application/json
required
name
required
string non-empty
expires_at
string or null <date-time>

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "token": {
    },
  • "value": "string"
}

Revoke a Service account token

Revokes the token at once. Web session only: a token can never revoke a token.

Authorizations:
(sessionCookiecsrf)
path Parameters
service_account_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Service account public_id.

token_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Token id.

Responses

Response samples

Content type
application/problem+json
Example
{}

Organization

Organization settings, the outbound address policy, the Keyring status and severity values seen.

Read the Organization

Readable by every signed-in identity (the basic read of the Organization needs no Permission). Secrets (the outgoing heartbeat URL, proxy passwords) show only set and updated_at.

Authorizations:
sessionCookieapiToken

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "time_zone": "string",
  • "workday_start": "09:00",
  • "week_start": "monday",
  • "severity_label": "string",
  • "severity_mapping": [
    ],
  • "severity_styles": [
    ],
  • "critical_is_urgent": true,
  • "instance_labels": [
    ],
  • "retention": {
    },
  • "totp_required": "nobody",
  • "oidc_token_grace_seconds": 1,
  • "id": "AGK7M3QX9P2RTA",
  • "outgoing_heartbeat": {
    },
  • "etag": "string"
}

Update the Organization

Replaces the writable fields. Requires If-Match; a stale ETag gets 412. An omitted optional field keeps its stored value; an explicit null clears a nullable one. An omitted Secret field keeps the stored Secret. null on outgoing_heartbeat.url or a proxy password clears it. Every field is validated; an invalid one gets 422 at the full JSON pointer of the field, such as /severity_styles/1/color or /retention/alert_details_days, with invalid_format, duplicate, required, too_short, too_long, out_of_range or retention_order. A retention period or oidc_token_grace_seconds beyond its maximum, a workday_start that is not HH:MM on the 24-hour clock and a week_start that is not a day of the week are refused with 400 by request validation, invalid_format at /workday_start or /week_start; out_of_range and invalid_format are the second, defensive check of the same rules. A change is recorded in the Audit log as organization.updated with its before/after diff and announced with the organization hint; Severity levels and Instance labels apply to later evaluations only.

Authorizations:
(sessionCookiecsrf) apiToken
header Parameters
If-Match
required
string

ETag of the representation being replaced, as returned by the last read. A mismatch gets 412; a missing header gets 428.

Request Body schema: application/json
required
name
required
string non-empty
time_zone
required
string

IANA time zone used for times in messages.

workday_start
string^([01][0-9]|2[0-3]):[0-5][0-9]$

The start of the working day, organization.workday_start (default 09:00), a time of day HH:MM on the 24-hour clock, at which the Snooze presets end in their time zone. Omit it on an update to keep it. A change applies to Snoozes set afterwards and never moves one already set.

week_start
string (Weekday)
Enum: "monday" "tuesday" "wednesday" "thursday" "friday" "saturday" "sunday"

A day of the week. As the Organization's week_start it is organization.week_start (default monday), the first day of the week, on which the Snooze preset week_start ends at the start of the working day; omit it on an update to keep it.

severity_label
required
string

Label that carries severity.

required
Array of objects (SeverityMappingEntry)

Values of the severity label mapped to Severity levels. Unmapped values count as warning.

required
Array of objects (SeverityLevelStyle)
critical_is_urgent
required
boolean
instance_labels
required
Array of strings
required
object (RetentionSettings)

Retention periods in days, from 1 to 36500 (100 years). alert_group_summaries_days must be at least alert_details_days: details are always removed before the summary rows they belong to, and an update that breaks this gets 422 with retention_order. Details are the Alerts inside Alert Groups, Timeline entries and delivery events; Notes are not details: they are kept with the summary rows and deleted with them.

totp_required
required
string (TotpPolicy)
Enum: "nobody" "local_users" "everyone"

Who must enrol TOTP. local_users covers every account that has a password; an account that signs in through OIDC — created through OIDC or linked — is not one. A user has one TOTP enrolment, asked at every sign-in and kept when the account changes its sign-in method; on an OIDC sign-in oidc.skip_totp_with_idp_mfa may skip it.

oidc_token_grace_seconds
required
integer [ 1 .. 3153600000 ]

auth.oidc_token_grace (default 7 days), only for accounts that sign in through OIDC and for which the IdP granted no offline token: their Personal access tokens work while the owner's last OIDC sign-in is no older than this, and otherwise get 401 with oidc_recheck_required until the owner signs in through OIDC again. Accounts with an offline token are re-checked in the background instead and have no such limit. Service account tokens are not affected. Edited on Organization → Security.

required
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "time_zone": "string",
  • "workday_start": "09:00",
  • "week_start": "monday",
  • "severity_label": "string",
  • "severity_mapping": [
    ],
  • "severity_styles": [
    ],
  • "critical_is_urgent": true,
  • "instance_labels": [
    ],
  • "retention": {
    },
  • "totp_required": "nobody",
  • "oidc_token_grace_seconds": 1,
  • "outgoing_heartbeat": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "time_zone": "string",
  • "workday_start": "09:00",
  • "week_start": "monday",
  • "severity_label": "string",
  • "severity_mapping": [
    ],
  • "severity_styles": [
    ],
  • "critical_is_urgent": true,
  • "instance_labels": [
    ],
  • "retention": {
    },
  • "totp_required": "nobody",
  • "oidc_token_grace_seconds": 1,
  • "id": "AGK7M3QX9P2RTA",
  • "outgoing_heartbeat": {
    },
  • "etag": "string"
}

Read the outbound address policy

The outbound address policy with the rules that always apply. Needs organization:read.

Authorizations:
sessionCookieapiToken

Responses

Response samples

Content type
application/json
{
  • "policy": "standard",
  • "allowed": [
    ],
  • "denied": [
    ],
  • "always_blocked": [
    ],
  • "etag": "string"
}

Update the outbound address policy

Replaces the policy and its lists. Requires If-Match; a stale ETag gets 412. Each entry is a network in CIDR form or a bare address, a host name, or a domain written *.example.org; an entry that does not parse gets 422 with invalid_format and a repeated one duplicate, at /allowed/<i> or /denied/<i>. always_blocked is read-only and ignored. The change takes effect at once on every replica, idle pooled connections included, is recorded in the Audit log as outbound_policy.updated and is announced with the organization hint. Needs organization:write.

Authorizations:
(sessionCookiecsrf) apiToken
header Parameters
If-Match
required
string

ETag of the representation being replaced, as returned by the last read. A mismatch gets 412; a missing header gets 428.

Request Body schema: application/json
required
policy
required
string
Enum: "standard" "strict"
allowed
required
Array of strings

Allowed networks (CIDR), host names and domains.

denied
required
Array of strings

Denied networks, host names and domains. A denied entry always wins.

Responses

Request samples

Content type
application/json
{
  • "policy": "standard",
  • "allowed": [
    ],
  • "denied": [
    ]
}

Response samples

Content type
application/json
{
  • "policy": "standard",
  • "allowed": [
    ],
  • "denied": [
    ],
  • "always_blocked": [
    ],
  • "etag": "string"
}

Read the Keyring status

Every key id in the environment, which is active, which live replicas hold which, and whether anything still depends on an older key. Activation is the CLI command muster secrets rotate-key --activate <id> --actor <name>.

Authorizations:
sessionCookieapiToken

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

List severity values seen

Values of the severity label seen in the last organization.severity_values_window, with counts, the most frequent first and at most 500 values; unmapped values count as warning.

Authorizations:
sessionCookieapiToken

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "window_days": 0
}

Integrations

Integrations, their tokens, learned Alertmanager routes, the Alerts view and Stored Snapshots.

List integrations

Includes the built-in "Muster" Integration, marked builtin.

Authorizations:
sessionCookieapiToken
query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Create Integration

Authorizations:
(sessionCookiecsrf) apiToken
Request Body schema: application/json
required
name
required
string non-empty

Unique in the Organization.

description
string
connection_mode
required
string
Value: "webhook_only"

The Connection mode; in L1 the only mode is webhook_only (webhook-only in the glossary).

required
object (Labels)

Label names and values.

duplicate_window_seconds
required
integer >= 1
required
object (HeartbeatSettingsInput)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "connection_mode": "webhook_only",
  • "static_labels": {
    },
  • "duplicate_window_seconds": 1,
  • "heartbeat": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "connection_mode": "webhook_only",
  • "static_labels": {
    },
  • "duplicate_window_seconds": 1,
  • "id": "AGK7M3QX9P2RTA",
  • "builtin": true,
  • "heartbeat": {
    },
  • "ingest_url": "http://example.com",
  • "last_snapshot_at": "2019-08-24T14:15:22Z",
  • "snapshot_count": 0,
  • "warnings": [
    ],
  • "open_alert_group_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Read Integration

Authorizations:
sessionCookieapiToken
path Parameters
integration_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Integration public_id.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "connection_mode": "webhook_only",
  • "static_labels": {
    },
  • "duplicate_window_seconds": 1,
  • "id": "AGK7M3QX9P2RTA",
  • "builtin": true,
  • "heartbeat": {
    },
  • "ingest_url": "http://example.com",
  • "last_snapshot_at": "2019-08-24T14:15:22Z",
  • "snapshot_count": 0,
  • "warnings": [
    ],
  • "open_alert_group_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Update Integration

Replaces the writable fields. Requires If-Match; a stale ETag gets 412. An omitted optional field keeps its stored value; an explicit null clears a nullable one.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
integration_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Integration public_id.

header Parameters
If-Match
required
string

ETag of the representation being replaced, as returned by the last read. A mismatch gets 412; a missing header gets 428.

Request Body schema: application/json
required
name
required
string non-empty

Unique in the Organization.

description
string
connection_mode
required
string
Value: "webhook_only"

The Connection mode; in L1 the only mode is webhook_only (webhook-only in the glossary).

required
object (Labels)

Label names and values.

duplicate_window_seconds
required
integer >= 1
required
object (HeartbeatSettingsInput)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "connection_mode": "webhook_only",
  • "static_labels": {
    },
  • "duplicate_window_seconds": 1,
  • "heartbeat": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "connection_mode": "webhook_only",
  • "static_labels": {
    },
  • "duplicate_window_seconds": 1,
  • "id": "AGK7M3QX9P2RTA",
  • "builtin": true,
  • "heartbeat": {
    },
  • "ingest_url": "http://example.com",
  • "last_snapshot_at": "2019-08-24T14:15:22Z",
  • "snapshot_count": 0,
  • "warnings": [
    ],
  • "open_alert_group_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Delete Integration

Soft delete: its tokens stop working at once, its open Alerts are resolved with the reason "Integration {name} deleted", its Internal alerts are resolved, and its open Alert Groups are resolved. The built-in Integration cannot be deleted (409, builtin_immutable).

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
integration_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Integration public_id.

header Parameters
If-Match
string

Optional ETag; when present and stale, the request gets 412.

Responses

Response samples

Content type
application/problem+json
Example
{}

List Integration tokens

Values are never returned.

Authorizations:
sessionCookieapiToken
path Parameters
integration_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Integration public_id.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create an Integration token

The token allows ingestion and Heartbeat and nothing else. The value and the ready Alertmanager snippet that contains it are returned once; a new snippet means a new token.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
integration_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Integration public_id.

Request Body schema: application/json
optional
name
string

Optional label to tell tokens apart during rotation.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "token": {
    },
  • "value": "string",
  • "alertmanager_snippet": "string",
  • "heartbeat_snippet": "string"
}

Revoke an Integration token

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
integration_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Integration public_id.

integration_token_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Integration token id.

Responses

Response samples

Content type
application/problem+json
Example
{}

List learned Alertmanager routes

Routes taken from the groupKey of Snapshots, with the learned repeat interval and the resulting time to resolve by absence.

Authorizations:
sessionCookieapiToken
path Parameters
integration_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Integration public_id.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List the Alerts view of an Integration

The Alerts Muster currently tracks for the Integration. Resolved Alerts stay for retention.alert_details. Label filters follow the scheme of label on listAlertGroups.

Authorizations:
sessionCookieapiToken
path Parameters
integration_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Integration public_id.

query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

state
string (AlertState)
Enum: "firing" "resolved"

Filter by state.

label
Array of strings
Examples:
  • label=namespace="payments" - One Matcher
  • label=namespace="payments"&label=pod=~"api-.*" - Two Matchers, combined with AND

Label filter: one Alertmanager-syntax Matcher per repeat of the parameter, combined with AND. Each value is a whole matcher: label=namespace%3D%22payments%22&label=pod%3D~%22api-.*%22 means namespace="payments" and pod=~"api-.*". There is no per-label shorthand. On Alert Groups the Matchers are matched against the common labels — the labels every Alert of the group has with the same value — so the filter also works on summary rows after the Alerts were removed; a label the Alerts do not share counts as absent. On the Alerts view of an Integration they are matched against each Alert's labels.

q
string

Case-insensitive match on label values.

sort
string
Default: "-last_seen_at"
Enum: "last_seen_at" "-last_seen_at" "starts_at" "-starts_at"

Sort field; a leading - sorts descending.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

List Stored Snapshots

Kept for retention.stored_snapshots. Replay is the CLI command muster ingest replay.

Authorizations:
sessionCookieapiToken
query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

integration
required
string

Integration public_id.

from
string <date-time>

Start of the time range (RFC 3339, UTC).

to
string <date-time>

End of the time range (RFC 3339, UTC).

state
Array of strings (SnapshotState)
Items Enum: "pending" "processed" "failed"

Only Snapshots in these processing states.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Read a Stored Snapshot as received

Authorizations:
sessionCookieapiToken
path Parameters
stored_snapshot_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Stored Snapshot id.

Responses

Response samples

Content type
application/json
{
  • "id": "AGK7M3QX9P2RTA",
  • "integration": {
    },
  • "received_at": "2019-08-24T14:15:22Z",
  • "processed_at": "2019-08-24T14:15:22Z",
  • "size_bytes": 0,
  • "group_key": "string",
  • "alert_count": 0,
  • "truncated_alerts": 0,
  • "state": "pending",
  • "processing_error": "string",
  • "body": "string",
  • "content_type": "string",
  • "body_encoding": "utf8"
}

Ingest

Alertmanager webhook and Heartbeat endpoints on the ingest listener. Integration tokens only.

Receive an Alertmanager webhook

Checks the token, then the body size, stores the body as a Stored Snapshot exactly as received and answers 202 after the write commits, without waiting for processing. It never answers 400: a body that is not JSON, or does not look like an Alertmanager payload, is stored and fails later as a processing error (log event, muster_ingest_failed_snapshots_total, Stored Snapshot state failed), because Alertmanager does not retry a 4xx and the notification would be lost. Not rate-limited. Counted in muster_ingest_requests_total with the outcome accepted, unauthorized or too_large. The only 5xx is a failed write, which Alertmanager retries. Ingestion is excluded from request validation by the spec: the handler reads the raw body and the generated types are not used for it.

Authorizations:
integrationToken
Request Body schema: */*
required

Any bytes up to ingest.body_limit. Alertmanager sends application/json, and the webhook contact point of Grafana Alerting sends the same JSON; see AlertmanagerWebhook.

string <binary>

Responses

Response samples

Content type
application/problem+json
Example
{}

Receive an Alertmanager webhook (token in the path)

For senders that cannot set a header. Identical to ingestSnapshot. Logs record the route pattern, never the path.

path Parameters
ingest_token
required
string

An Integration token. Never logged.

Request Body schema: */*
required

Any bytes up to ingest.body_limit. Alertmanager sends application/json, and the webhook contact point of Grafana Alerting sends the same JSON; see AlertmanagerWebhook.

string <binary>

Responses

Response samples

Content type
application/problem+json
Example
{}

Heartbeat signal (GET)

Any request carrying one of the Integration's tokens counts as a signal; the body is ignored. The first signal moves the Heartbeat from waiting to live. While the Integration's Heartbeat is off, the request is answered 204 and nothing is recorded.

Authorizations:
integrationToken

Responses

Response samples

Content type
application/problem+json
Example
{}

Heartbeat signal (POST)

Any request carrying one of the Integration's tokens counts as a signal; the body is ignored. The first signal moves the Heartbeat from waiting to live. While the Integration's Heartbeat is off, the request is answered 204 and nothing is recorded.

Authorizations:
integrationToken

Responses

Response samples

Content type
application/problem+json
Example
{}

Heartbeat signal (GET, token in the path)

path Parameters
ingest_token
required
string

An Integration token. Never logged.

Responses

Response samples

Content type
application/problem+json
Example
{}

Heartbeat signal (POST, token in the path)

path Parameters
ingest_token
required
string

An Integration token. Never logged.

Responses

Response samples

Content type
application/problem+json
Example
{}

Messenger callbacks

Mattermost button presses and the optional Telegram webhook, on the ingest listener.

Receive a Mattermost button press

Sent by the Mattermost server. Mattermost does not sign the request: Muster verifies the signed action id with the key it names, checks that post_id and channel_id belong to the post the id was issued for, maps user_id to a User through the Account link of this Connection and dispatches the Command with the Transport mattermost. Every request is answered with 200 and a JSON object, an unknown or deleted Connection, a bad signature and a body that is not JSON or does not match MattermostActionRequest included; request validation does not answer 400 here. Whatever the person who pressed must read — a refusal, a failure, "not linked", or "not verified" for a press on a post Muster delivered in that channel — goes first as a separate ephemeral post, shown in the channel view, and the answer is then an empty object. That post needs the create_post_ephemeral permission, which a bot with the role Member lacks; when it is refused, or fails in any other way, the answer carries the text as ephemeral_text, which Mattermost shows to that person alone in the Thread of the Root message and which needs no permission. Every other answer is an empty object, so the endpoint tells a caller nothing about which Connection ids exist. The answer never carries update: only the delivery worker edits the Root message.

path Parameters
connection_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Connection public_id.

Request Body schema: application/json
required
user_id
required
string
user_name
string
channel_id
required
string
team_id
string
post_id
required
string
trigger_id
string
type
string
data_source
string
required
object (MattermostActionContext)

The integration data Muster put on the button. Mattermost does not sign the request, so authenticity rests on the signed action id.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "user_id": "string",
  • "user_name": "string",
  • "channel_id": "string",
  • "team_id": "string",
  • "post_id": "string",
  • "trigger_id": "string",
  • "type": "string",
  • "data_source": "string",
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "ephemeral_text": "string",
  • "skip_slack_parsing": true
}

Receive a Telegram update (webhook update mode)

Used only when the Connection's update mode is webhook. A request without the right secret token header, or for a Connection that does not exist or is not in webhook mode, is answered 401 and changes nothing.

Authorizations:
telegramSecretToken
path Parameters
connection_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Connection public_id.

Request Body schema: application/json
required
update_id
required
integer <int64>
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "update_id": 0
}

Response samples

Content type
application/problem+json
{}

Receive a Bridge event (push event delivery)

Used only when the Bridge Connection's event delivery mode is push: the bridge posts each event, one per request, signed as Standard Webhooks specifies with the Connection's push secret. Muster verifies webhook-signature — v1, followed by the base64 of HMAC-SHA256 over <webhook-id>.<webhook-timestamp>.<body> with the decoded secret, any of several signatures separated by spaces — in constant time, refuses a webhook-timestamp further than bridge.push_tolerance from its real clock, and requires webhook-id to equal the event's id. It handles each event id of a Connection once within bridge.event_dedup_window, answers the person behind the event, when it does, before it answers 204, and answers 204 also for an id it handled before. A bad signature, a timestamp out of range, an unknown or deleted Connection and a Connection in poll mode are all answered 401 and change nothing, so the endpoint reveals nothing about which Connections exist; a body that is no event of the Bridge protocol, or whose id is not webhook-id, is answered 400, and the bridge drops it; an event whose handling failed is answered 500, is not recorded as handled, and the bridge sends it again. Request validation does not answer 400 here: the handler decides every answer.

path Parameters
connection_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Connection public_id.

header Parameters
webhook-id
required
string^[!-~]{1,200}$

The event's id, kept across retries.

webhook-timestamp
required
string^[0-9]{1,12}$

Unix time of this attempt, in seconds.

webhook-signature
required
string >= 4 characters

v1,<base64 HMAC-SHA256>; several signatures separated by spaces are allowed while a secret is rotated.

Request Body schema: application/json
required
id
required
string^[!-~]{1,200}$

Stable across retries and polls; Muster handles each id of a Connection once. Printable ASCII without spaces, so that it can travel as the webhook-id header.

type
required
string
Value: "press"
occurred_at
required
string <date-time>

When it happened in the messenger, or when the bridge learned of it.

message_id
required
string

The message the button belongs to, a Root message or a Thread reply.

required
object (BridgePerson)

A messenger account as a bridge names it, a copy of the schema Person of the Bridge protocol.

data
required
string

The button's data, unchanged.

Responses

Request samples

Content type
application/json
Example
{
  • "id": "string",
  • "type": "press",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "message_id": "string",
  • "user": {
    },
  • "data": "string"
}

Response samples

Content type
application/problem+json
{}

Routes

Routes, Matchers, Group key previews, profiles and suggestions.

List Routes in evaluation order

The first Route whose Matchers all match takes an Alert. The Default route is always last. The ETag covers the order and is what reorderRoutes expects in If-Match.

Authorizations:
sessionCookieapiToken

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a Route

Inserted before the Default route. Fields omitted from policy are not defaulted: fetch a profile with listRouteProfiles to pre-fill the form. Templates are parsed and dry-run against recent Stored Snapshots; a template that fails is refused with 422 and the error position.

Authorizations:
(sessionCookiecsrf) apiToken
Request Body schema: application/json
required
name
required
string non-empty

Unique in the Organization.

description
string
required
Array of objects (Matcher)

Combined with AND. The Default route has none.

urgent
required
boolean
group_key
required
Array of strings

Label names whose values split the Route's Alerts into Alert Groups. A missing label counts as an empty value.

destination_ids
required
Array of strings (PublicId) [ items^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za... ]
required
object (RoutePolicy)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "matchers": [
    ],
  • "urgent": true,
  • "group_key": [
    ],
  • "destination_ids": [
    ],
  • "policy": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "matchers": [
    ],
  • "urgent": true,
  • "group_key": [
    ],
  • "destination_ids": [
    ],
  • "policy": {
    },
  • "id": "AGK7M3QX9P2RTA",
  • "position": 0,
  • "is_default": true,
  • "destinations": [
    ],
  • "template_error": {
    },
  • "storm_active": true,
  • "storm": {
    },
  • "open_alert_group_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Read a Route

Authorizations:
sessionCookieapiToken
path Parameters
route_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Route public_id.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "matchers": [
    ],
  • "urgent": true,
  • "group_key": [
    ],
  • "destination_ids": [
    ],
  • "policy": {
    },
  • "id": "AGK7M3QX9P2RTA",
  • "position": 0,
  • "is_default": true,
  • "destinations": [
    ],
  • "template_error": {
    },
  • "storm_active": true,
  • "storm": {
    },
  • "open_alert_group_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Update a Route

Replaces the writable fields. Requires If-Match; a stale ETag gets 412. An omitted optional field keeps its stored value; an explicit null clears a nullable one.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
route_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Route public_id.

header Parameters
If-Match
required
string

ETag of the representation being replaced, as returned by the last read. A mismatch gets 412; a missing header gets 428.

Request Body schema: application/json
required
name
required
string non-empty

Unique in the Organization.

description
string
required
Array of objects (Matcher)

Combined with AND. The Default route has none.

urgent
required
boolean
group_key
required
Array of strings

Label names whose values split the Route's Alerts into Alert Groups. A missing label counts as an empty value.

destination_ids
required
Array of strings (PublicId) [ items^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za... ]
required
object (RoutePolicy)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "matchers": [
    ],
  • "urgent": true,
  • "group_key": [
    ],
  • "destination_ids": [
    ],
  • "policy": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "matchers": [
    ],
  • "urgent": true,
  • "group_key": [
    ],
  • "destination_ids": [
    ],
  • "policy": {
    },
  • "id": "AGK7M3QX9P2RTA",
  • "position": 0,
  • "is_default": true,
  • "destinations": [
    ],
  • "template_error": {
    },
  • "storm_active": true,
  • "storm": {
    },
  • "open_alert_group_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Delete a Route

Refused with 409 default-route-immutable for the Default route and with 409 route-has-open-alert-groups (carrying open_alert_group_count) while open Alert Groups remain; move them first with moveOpenAlertGroups.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
route_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Route public_id.

header Parameters
If-Match
string

Optional ETag; when present and stale, the request gets 412.

Responses

Response samples

Content type
application/problem+json
Example
{}

Reorder Routes

Replaces the order of all Routes except the Default route, which cannot be moved. If-Match carries the ETag of listRoutes; a stale one gets 412. A list that contains the Default route is 409 (default-route-immutable); a set of ids that differs from the current set is 422 (route_set_mismatch).

Authorizations:
(sessionCookiecsrf) apiToken
header Parameters
If-Match
required
string

ETag of the representation being replaced, as returned by the last read. A mismatch gets 412; a missing header gets 428.

Request Body schema: application/json
required
route_ids
required
Array of strings (PublicId) [ items^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za... ]

Every Route except the Default route, in the new order.

Responses

Request samples

Content type
application/json
{
  • "route_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Move open Alert Groups to the Default route

Adds a moved_to_default_route Timeline entry to each moved Alert Group. Afterwards the Route can be deleted. A moved Alert Group keeps its Group key values but takes no new Alerts and never reopens; it stays open until its Alerts resolve or a person resolves it.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
route_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Route public_id.

Responses

Response samples

Content type
application/json
{
  • "moved": 0
}

List Route profiles

The two starting sets of Route settings, On-call and Informational, read from the built-in defaults. They only pre-fill the create form; they cannot be edited or stored.

Authorizations:
sessionCookieapiToken

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Preview a Group key

Counts the Alert Groups that the Stored Snapshots of the period would have produced with the current and with the proposed Group key.

Authorizations:
(sessionCookiecsrf) apiToken
Request Body schema: application/json
required
route_id
string or null (NullablePublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...

A saved Route; its current Group key is the "current" side.

proposed_group_key
required
Array of strings
period_seconds
integer >= 1

Defaults to routing.group_key_preview_period; at most retention.stored_snapshots.

Array of objects (Matcher)

Matchers to preview instead of, or without, a saved Route's own.

Responses

Request samples

Content type
application/json
{
  • "route_id": "AGK7M3QX9P2RTA",
  • "proposed_group_key": [
    ],
  • "period_seconds": 1,
  • "matchers": [
    ]
}

Response samples

Content type
application/json
{
  • "period_seconds": 0,
  • "truncated": true,
  • "current": {
    },
  • "proposed": {
    }
}

List Route suggestions

A Route for MusterHeartbeatLost when an Integration has a Heartbeat and no Route other than the Default route matches it; from the first Destination on, a Route for alertname=~"Muster.*". Dismissals are remembered per user.

Authorizations:
sessionCookieapiToken

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Accept a Route suggestion

Creates the suggested Route at the top of the list; the Route for internal_alerts goes directly below the last Route other than the Default route that already takes an Internal alert, such as the Route for MusterHeartbeatLost, and at the top when none does. 409 (suggestion_obsolete) when it no longer applies: a matching Route exists now, it was accepted already, or no Destination exists for internal_alerts; 422 (required at /destination_ids) when internal_alerts is accepted without Destinations.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
suggestion_id
required
string (RouteSuggestionId)
Enum: "heartbeat_lost" "internal_alerts"

Route suggestion id.

Request Body schema: application/json
optional
destination_ids
Array of strings (PublicId) [ items^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za... ]

Destinations for the created Route; required for internal_alerts.

Responses

Request samples

Content type
application/json
{
  • "destination_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "matchers": [
    ],
  • "urgent": true,
  • "group_key": [
    ],
  • "destination_ids": [
    ],
  • "policy": {
    },
  • "id": "AGK7M3QX9P2RTA",
  • "position": 0,
  • "is_default": true,
  • "destinations": [
    ],
  • "template_error": {
    },
  • "storm_active": true,
  • "storm": {
    },
  • "open_alert_group_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Dismiss a Route suggestion

Remembered for the calling user only, so Service account tokens get 403 (service_account_not_allowed). 409 (suggestion_obsolete) when it no longer applies.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
suggestion_id
required
string (RouteSuggestionId)
Enum: "heartbeat_lost" "internal_alerts"

Route suggestion id.

Responses

Response samples

Content type
application/problem+json
Example
{}

Alert groups

Alert Groups, their Alerts, Timeline, Notes, delivery state, statistics and Commands.

List Alert Groups

The main working list. Without status it returns open Alert Groups (firing, acknowledged, snoozed). Without from and to it covers the last alert_group.list_range (7 days) and selects Alert Groups whose lifetime overlaps the range, so one that has been firing for weeks is always included. Search matches #N and text in the title or summary. Changes arrive as alert-group and alert-groups hints.

Authorizations:
sessionCookieapiToken
query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

status
Array of strings (AlertGroupStatus)
Items Enum: "firing" "acknowledged" "snoozed" "resolved"

Only these statuses. Default: firing, acknowledged and snoozed.

route
Array of strings

Only these Routes (public_id).

integration
Array of strings

Only Alert Groups with Alerts from these Integrations (public_id).

severity
Array of strings (SeverityLevel)
Items Enum: "critical" "warning" "info"

Only these Severity levels.

urgent
boolean

Only Urgent (true) or non-Urgent (false) Alert Groups.

resolved_by
string (ResolverKind)
Enum: "user" "system"

Only Alert Groups resolved by a person or by the system.

resolve_reason
string (ResolveReason)
Enum: "resolved" "gone" "stale" "integration_deleted"

With resolved_by=system: the reason.

reopened
boolean

True: Reopen count above zero.

label
Array of strings
Examples:
  • label=namespace="payments" - One Matcher
  • label=namespace="payments"&label=pod=~"api-.*" - Two Matchers, combined with AND

Label filter: one Alertmanager-syntax Matcher per repeat of the parameter, combined with AND. Each value is a whole matcher: label=namespace%3D%22payments%22&label=pod%3D~%22api-.*%22 means namespace="payments" and pod=~"api-.*". There is no per-label shorthand. On Alert Groups the Matchers are matched against the common labels — the labels every Alert of the group has with the same value — so the filter also works on summary rows after the Alerts were removed; a label the Alerts do not share counts as absent. On the Alerts view of an Integration they are matched against each Alert's labels.

owner
string

A user public_id, me (the calling User; 422 for a Service account token), or none for Alert Groups nobody owns, resolved ones included.

snoozed_no_end
boolean

True: only Alert Groups snoozed with no end. False: every Alert Group but those.

delivery_problem
boolean

Any Destination is Not delivered, waiting for a Broken Destination, deleted in the messenger or has a Thread not attached.

unclaimed
boolean

Only Unclaimed Alert Groups.

from
string <date-time>

Start of the time range (RFC 3339, UTC).

to
string <date-time>

End of the time range (RFC 3339, UTC).

number
integer >= 1

The Alert Group with exactly this #N. Neither the default time range nor the default status applies: a number is found whatever its age and status (while its summary row is kept); the other filters still apply.

q
string

Search by text in the title or summary, case-insensitive and matching parts of words. A #N typed here is the same as number.

sort
string
Default: "-started_at"
Enum: "started_at" "-started_at" "last_changed_at" "-last_changed_at"

Sort field; a leading - sorts descending.

label_columns
Array of strings

Label names whose shared value is returned in label_values of each Alert Group.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Count Alert Groups per status

Counts per status tab for the same filters as listAlertGroups, status excluded.

Authorizations:
sessionCookieapiToken
query Parameters
route
Array of strings

Only these Routes (public_id).

integration
Array of strings

Only Alert Groups with Alerts from these Integrations (public_id).

severity
Array of strings (SeverityLevel)
Items Enum: "critical" "warning" "info"

Only these Severity levels.

urgent
boolean

Only Urgent (true) or non-Urgent (false) Alert Groups.

resolved_by
string (ResolverKind)
Enum: "user" "system"

Only Alert Groups resolved by a person or by the system.

resolve_reason
string (ResolveReason)
Enum: "resolved" "gone" "stale" "integration_deleted"

With resolved_by=system: the reason.

reopened
boolean

True: Reopen count above zero.

label
Array of strings
Examples:
  • label=namespace="payments" - One Matcher
  • label=namespace="payments"&label=pod=~"api-.*" - Two Matchers, combined with AND

Label filter: one Alertmanager-syntax Matcher per repeat of the parameter, combined with AND. Each value is a whole matcher: label=namespace%3D%22payments%22&label=pod%3D~%22api-.*%22 means namespace="payments" and pod=~"api-.*". There is no per-label shorthand. On Alert Groups the Matchers are matched against the common labels — the labels every Alert of the group has with the same value — so the filter also works on summary rows after the Alerts were removed; a label the Alerts do not share counts as absent. On the Alerts view of an Integration they are matched against each Alert's labels.

owner
string

A user public_id, me (the calling User; 422 for a Service account token), or none for Alert Groups nobody owns, resolved ones included.

snoozed_no_end
boolean

True: only Alert Groups snoozed with no end. False: every Alert Group but those.

delivery_problem
boolean

Any Destination is Not delivered, waiting for a Broken Destination, deleted in the messenger or has a Thread not attached.

unclaimed
boolean

Only Unclaimed Alert Groups.

from
string <date-time>

Start of the time range (RFC 3339, UTC).

to
string <date-time>

End of the time range (RFC 3339, UTC).

q
string

Search by text in the title or summary, case-insensitive and matching parts of words. A #N typed here is the same as number.

Responses

Response samples

Content type
application/json
{
  • "firing": 0,
  • "acknowledged": 0,
  • "snoozed": 0,
  • "resolved": 0,
  • "all": 0
}

Read Alert Group statistics

Number of Alert Groups, time to acknowledge and time to resolve (median and 95th percentile), as totals and per day of start, from the summary rows, one item per Route or per Integration as group_by says. Narrow it with route or integration ids (the one that matches group_by); without them every Route or Integration is returned. An Alert Group with Alerts from several Integrations counts for each.

Authorizations:
sessionCookieapiToken
query Parameters
group_by
required
string
Enum: "route" "integration"

What one item stands for.

route
Array of strings (PublicId) [ items^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za... ]
Example: route=AGK7M3QX9P2RTA

Only these Routes (public_id); with group_by=route.

integration
Array of strings (PublicId) [ items^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za... ]
Example: integration=AGK7M3QX9P2RTA

Only these Integrations (public_id); with group_by=integration.

from
string <date-time>

Start of the time range (RFC 3339, UTC).

to
string <date-time>

End of the time range (RFC 3339, UTC).

time_zone
string

IANA time zone that splits days; defaults to the Organization's.

Responses

Response samples

Content type
application/json
{
  • "group_by": "route",
  • "from": "2019-08-24T14:15:22Z",
  • "to": "2019-08-24T14:15:22Z",
  • "items": [
    ]
}

Read an Alert Group

An Alert Group whose details were removed by retention opens as its summary with the notice details_removed; its Notes stay until the summary row is removed.

Authorizations:
sessionCookieapiToken
path Parameters
alert_group_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Alert Group public_id.

Responses

Response samples

Content type
application/json
{
  • "id": "AGK7M3QX9P2RTA",
  • "number": 0,
  • "title": "string",
  • "summary": "string",
  • "status": "firing",
  • "owner": {
    },
  • "snooze_until": "2019-08-24T14:15:22Z",
  • "snoozed_by": {
    },
  • "severity_level": "critical",
  • "urgent": true,
  • "route": {
    },
  • "integrations": [
    ],
  • "started_at": "2019-08-24T14:15:22Z",
  • "resolved_at": "2019-08-24T14:15:22Z",
  • "last_changed_at": "2019-08-24T14:15:22Z",
  • "reopen_count": 0,
  • "firing_alert_count": 0,
  • "resolved_alert_count": 0,
  • "resolution": {
    },
  • "unclaimed": true,
  • "next_notice": {
    },
  • "delivery_problem": true,
  • "details_removed": true,
  • "group_labels": {
    },
  • "common_labels": {
    },
  • "common_annotations": {
    },
  • "label_values": {
    },
  • "notices": [
    ],
  • "links": [
    ],
  • "allowed_commands": [
    ]
}

List the Alerts of an Alert Group

Authorizations:
sessionCookieapiToken
path Parameters
alert_group_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Alert Group public_id.

query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

state
string (AlertState)
Enum: "firing" "resolved"

Filter by firing or resolved; firing Alerts come first.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Read the Timeline of an Alert Group

Entries of all kinds, with delivery events merged in by time as the kind delivery. Lifecycle events carry event, loudness and mentions. Notes are kept as long as the summary row, so after the details were removed by retention the Timeline still returns them.

Authorizations:
sessionCookieapiToken
path Parameters
alert_group_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Alert Group public_id.

query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

kind
Array of strings (TimelineKind)
Items Enum: "status" "alerts" "notes" "timers" "delivery" "system"

Only these kinds.

order
string
Default: "desc"
Enum: "asc" "desc"

Newest first by default.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": null
}

List previous Alert Groups with the same key

Alert Groups of the same Route with the same Group key values, newest first.

Authorizations:
sessionCookieapiToken
path Parameters
alert_group_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Alert Group public_id.

query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Read delivery state per Destination

Authorizations:
sessionCookieapiToken
path Parameters
alert_group_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Alert Group public_id.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Acknowledge

From firing or snoozed: the caller becomes the Owner and a Snooze ends. By the current Owner it changes nothing (outcome unchanged). By another user it is a Takeover: ownership moves, a Loud event mentions the previous Owner. A Personal access token acts as its User and may; a Service account token cannot become an Owner and is refused with 409 command-refused and the code owner_must_be_user. Other refusals: already_resolved.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
alert_group_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Alert Group public_id.

Responses

Response samples

Content type
application/json
{
  • "outcome": "done",
  • "alert_group": {
    }
}

Unacknowledge

Allowed to every user with the Permission, not only the Owner. The Alert Group becomes firing without an Owner. Refused with the code not_acknowledged.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
alert_group_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Alert Group public_id.

Responses

Response samples

Content type
application/json
{
  • "outcome": "done",
  • "alert_group": {
    }
}

Resolve

Resolves by the user, with an optional Note recorded in the same request. Refused with the code already_resolved.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
alert_group_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Alert Group public_id.

Request Body schema: application/json
optional
note
string [ 1 .. 4000 ] characters

Optional Note recorded in the same request.

Responses

Request samples

Content type
application/json
{
  • "note": "string"
}

Response samples

Content type
application/json
{
  • "outcome": "done",
  • "alert_group": {
    }
}

Unresolve

Only for an Alert Group a person resolved; messengers never offer it. Refused, in this order, with the codes not_resolved, resolved_automatically, route_deleted, newer_alert_group_exists (see related_alert_group) and all_alerts_resolved.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
alert_group_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Alert Group public_id.

Responses

Response samples

Content type
application/json
{
  • "outcome": "done",
  • "alert_group": {
    }
}

Snooze

A Snooze until a future time (until), with no end (no_end: true) or until a Snooze preset (preset), chosen explicitly. A preset's end is computed when the Command runs and stored as an instant. Allowed from firing, acknowledged and snoozed.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
alert_group_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Alert Group public_id.

Request Body schema: application/json
required
until
string <date-time>

A future time.

no_end
boolean
Value: true

Snooze until someone unsnoozes it.

preset
string (SnoozePreset)
Enum: "tomorrow" "week_start"

A Snooze preset. tomorrow ends at the first start of the working day (organization.workday_start) after now, week_start at the first start of the working day on the first day of the week (organization.week_start) after now. After now is strict, so at the start itself the next one counts, and before the start of the working day tomorrow ends the same morning.

time_zone
string

IANA time zone in which the end of preset is computed; only with preset.

Responses

Request samples

Content type
application/json
Example
{
  • "until": "2026-10-04T08:00:00Z"
}

Response samples

Content type
application/json
{
  • "outcome": "done",
  • "alert_group": {
    }
}

Unsnooze

The Alert Group becomes firing without an Owner. Refused with the code not_snoozed.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
alert_group_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Alert Group public_id.

Responses

Response samples

Content type
application/json
{
  • "outcome": "done",
  • "alert_group": {
    }
}

List Notes

Notes are kept as long as the Alert Group's summary row (retention.alert_group_summaries), also after its Alerts and Timeline were removed by retention, and are deleted with the summary row.

Authorizations:
sessionCookieapiToken
path Parameters
alert_group_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Alert Group public_id.

query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Add a Note

Adds a Note. Service accounts may add Notes; the author is shown as the Service account.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
alert_group_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Alert Group public_id.

Request Body schema: application/json
required
body
required
string [ 1 .. 4000 ] characters

At most alert_group.note_max_length characters.

Responses

Request samples

Content type
application/json
{
  • "body": "string"
}

Response samples

Content type
application/json
{
  • "id": "AGK7M3QX9P2RTA",
  • "body": "string",
  • "author": {
    },
  • "transport": "ui",
  • "created_at": "2019-08-24T14:15:22Z"
}

Answer a Reminder with "Still on it"

Owner only. Recorded in the Timeline like a press in a messenger; it does not reset the Reminder interval. Refused with 409 command-refused and the codes not_owner, no_reminder_pending and, for a Service account token, owner_must_be_user.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
alert_group_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Alert Group public_id.

Responses

Response samples

Content type
application/json
{
  • "outcome": "done",
  • "alert_group": {
    }
}

Run a Command on several Alert Groups

Acknowledge, Resolve, Snooze or Unsnooze on up to alert_group.bulk_max Alert Groups. Each goes through the dispatcher on its own, with its own Audit log and Timeline entry; a refusal never stops the others. Bulk Acknowledge skips Alert Groups another user owns and never makes a Takeover. x-permission lists alternatives: the caller needs the Permission of the chosen command (acknowledge needs alert-groups:acknowledge, resolve needs alert-groups:resolve, snooze and unsnooze need alert-groups:snooze). A bulk Snooze with a preset computes its end once, so every Alert Group gets the same end; the pointers of its problems start with /snooze.

Authorizations:
(sessionCookiecsrf) apiToken
Request Body schema: application/json
required
command
required
string
Enum: "acknowledge" "resolve" "snooze" "unsnooze"
alert_group_ids
required
Array of strings (PublicId) [ 1 .. 100 ] items [ items^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za... ]

At most alert_group.bulk_max.

note
string <= 4000 characters

For resolve; optional.

object (SnoozeRequest)

Required for snooze.

Responses

Request samples

Content type
application/json
Example
{
  • "command": "snooze",
  • "alert_group_ids": [
    ],
  • "snooze": {
    }
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

List the ends of the Snooze presets

The end that a Snooze with each Snooze preset would set now, in the order tomorrow, week_start, computed like the Snooze itself from organization.workday_start and organization.week_start on the business clock. The time zone is time_zone when given, else the profile time zone of the User the caller acts as, else the Organization's; the answer names the one it used. A time zone Muster does not know (or Local) is 422 invalid_format at /query/time_zone. It reads and changes nothing else.

Authorizations:
sessionCookieapiToken
query Parameters
time_zone
string
Example: time_zone=Europe/Berlin

IANA time zone of the ends; defaults to the caller's profile time zone, else the Organization's.

Responses

Response samples

Content type
application/json
{
  • "time_zone": "Europe/Berlin",
  • "workday_start": "09:00",
  • "week_start": "monday",
  • "items": [
    ]
}

Live updates

The server-sent events stream of change hints at /live-updates.

Stream change hints

Server-sent events (text/event-stream). OpenAPI 3.1 cannot type event streams, so the events are described by HintEvent.

Each event has the name hint, an id line and a JSON data line {type, id}. A hint carries no data: the client re-reads through the API, so authorization stays in one place. The stream starts with retry: 3000 (the reconnect delay in milliseconds) and a comment line (: keepalive) follows periodically. After a reconnect the client invalidates everything; Last-Event-ID is not replayed. When the session expires or is ended, the server closes the stream; the browser's reconnect then gets 401, which makes EventSource stop for good, and the SPA goes to the sign-in page. The stream follows a web session; a token gets 403 (session_required).

Authorizations:
sessionCookie

Responses

Response samples

Content type
application/problem+json
Example
{}

Connections

Mattermost and Telegram Connections.

List connections

Authorizations:
sessionCookieapiToken
query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

type
string (ConnectionType)
Enum: "mattermost" "telegram" "bridge"

Filter by type.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Create Connection

type selects Mattermost, Telegram or Bridge. The bot token and the push secret are write-only Secrets.

Authorizations:
(sessionCookiecsrf) apiToken
Request Body schema: application/json
required
type
required
string
name
required
string non-empty
server_url
required
string <uri>
required
object (Limiter)

A rate limit of limit calls per per_seconds.

bot_token
string <password>

Write-only Secret. Omit on update to keep the stored one.

required
object (ProxyConfigInput)

Per-client proxy as written. Omitting password keeps the stored one; null clears it.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "mattermost",
  • "name": "string",
  • "server_url": "http://example.com",
  • "limiter": {
    },
  • "bot_token": "pa$$word",
  • "proxy": {
    }
}

Response samples

Content type
application/json
Example
{
  • "type": "mattermost",
  • "name": "string",
  • "server_url": "http://example.com",
  • "limiter": {
    },
  • "id": "AGK7M3QX9P2RTA",
  • "bot_token_status": {
    },
  • "bot_username": "string",
  • "proxy": {
    },
  • "destination_count": 0,
  • "callback_url": "http://example.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Check a Connection before saving it

Checks a draft of a Connection of any type, as its form holds it — the address, the bot token typed in the form, the proxy and, for a Bridge, the event delivery mode — with the steps and step codes of checkConnection, and stores nothing: no Connection, no bot name, no info, no Audit log entry. Which token goes where: a bot_token in the draft is sent to the address in the draft; without one, the stored token of connection_id is sent only when the draft's address, normalized as a save normalizes it, and its proxy are the saved ones; otherwise only the dry probe of the type runs, without any token, and the other steps are reported skipped — Mattermost GET <server_url>/api/v4/system/ping, Telegram GET <bot_api_base_url>/bot0:x/getMe, a Bridge GET <base_url>/v1/info. A stored proxy password is used only with the saved proxy type and address. A connection_id that names no Connection, a deleted one or one of another type answers 422 unknown_id at /connection_id; an address or a proxy that a save would refuse answers 422 at its pointer. Runs on the interactive path: a draft with a connection_id takes its limiter token from that Connection, and when none is free within delivery.interactive_budget the answer is 503 with Retry-After; a draft of a new Connection has no limiter and waits for none.

Authorizations:
(sessionCookiecsrf) apiToken
Request Body schema: application/json
required
type
required
string
server_url
required
string <uri>

The server URL as MattermostConnectionBase takes it.

bot_token
string <password>

A bot token typed in the form, sent only to server_url. Omit it to use the stored token of connection_id, which goes only to its saved server URL through its saved proxy.

object (ProxyConfigInput)

Per-client proxy as written. Omitting password keeps the stored one; null clears it.

connection_id
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...

The saved Mattermost Connection that the form edits; omit it for a new one. An omitted proxy is its saved proxy, and no proxy without it.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "mattermost",
  • "server_url": "http://example.com",
  • "bot_token": "pa$$word",
  • "proxy": {
    },
  • "connection_id": "AGK7M3QX9P2RTA"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "steps": [
    ],
  • "warnings": [
    ],
  • "bot_name": "string",
  • "webhook_set": true,
  • "pending_updates": 0,
  • "info": {
    },
  • "request_log_run": "AGK7M3QX9P2RTA"
}

Read Connection

Authorizations:
sessionCookieapiToken
path Parameters
connection_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Connection public_id.

Responses

Response samples

Content type
application/json
Example
{
  • "type": "mattermost",
  • "name": "string",
  • "server_url": "http://example.com",
  • "limiter": {
    },
  • "id": "AGK7M3QX9P2RTA",
  • "bot_token_status": {
    },
  • "bot_username": "string",
  • "proxy": {
    },
  • "destination_count": 0,
  • "callback_url": "http://example.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Update Connection

Replaces the writable fields. Requires If-Match; a stale ETag gets 412. An omitted optional field keeps its stored value; an explicit null clears a nullable one. An omitted Secret field keeps the stored Secret.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
connection_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Connection public_id.

header Parameters
If-Match
required
string

ETag of the representation being replaced, as returned by the last read. A mismatch gets 412; a missing header gets 428.

Request Body schema: application/json
required
type
required
string
name
required
string non-empty
server_url
required
string <uri>
required
object (Limiter)

A rate limit of limit calls per per_seconds.

bot_token
string <password>

Write-only Secret. Omit on update to keep the stored one.

required
object (ProxyConfigInput)

Per-client proxy as written. Omitting password keeps the stored one; null clears it.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "mattermost",
  • "name": "string",
  • "server_url": "http://example.com",
  • "limiter": {
    },
  • "bot_token": "pa$$word",
  • "proxy": {
    }
}

Response samples

Content type
application/json
Example
{
  • "type": "mattermost",
  • "name": "string",
  • "server_url": "http://example.com",
  • "limiter": {
    },
  • "id": "AGK7M3QX9P2RTA",
  • "bot_token_status": {
    },
  • "bot_username": "string",
  • "proxy": {
    },
  • "destination_count": 0,
  • "callback_url": "http://example.com",
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Delete Connection

A Connection used by Destinations cannot be deleted: 409 (in_use). Deleted Destinations do not count; deleting the Connection abandons the final edits still pending for them, which end as Not delivered.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
connection_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Connection public_id.

header Parameters
If-Match
string

Optional ETag; when present and stale, the request gets 412.

Responses

Response samples

Content type
application/problem+json
Example
{}

Check a Connection

Mattermost verifies the token and returns the bot's name. Telegram works in steps and reports the latency and path of each: a dry probe without the token, getMe, getWebhookInfo. With base_url in the body only the dry probe runs against that unsaved address, without the token: a stored token is sent only to the saved address of its Connection, through its saved proxy; checkConnectionDraft checks an unsaved address with the token typed again. A Bridge Connection is checked in two steps: info calls getInfo of the Bridge protocol with the token, and a passing info is stored on the Connection and returned as info; event_delivery checks that the bridge offers the Connection's event delivery mode. Runs on the interactive path: when no limiter token is free within delivery.interactive_budget, the answer is 503 with Retry-After.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
connection_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Connection public_id.

Request Body schema: application/json
optional
base_url
string or null

An unsaved Telegram Bot API base URL. When set, only the dry probe runs against it, without the token: a stored token is sent only to the saved address of its Connection. Kept for API clients; checkConnectionDraft checks a draft with its token typed again.

Responses

Request samples

Content type
application/json
{
  • "base_url": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "steps": [
    ],
  • "warnings": [
    ],
  • "bot_name": "string",
  • "webhook_set": true,
  • "pending_updates": 0,
  • "info": {
    },
  • "request_log_run": "AGK7M3QX9P2RTA"
}

List channels visible to the bot

Mattermost Connections only; loads the team and channel pickers through the bot. A Telegram or Bridge Connection answers 409: the Bridge protocol has no channel list, the Admin enters the channel id. Requires connections:write because it calls out with the bot token. Runs on the interactive path: when no limiter token is free within delivery.interactive_budget, the answer is 503 with Retry-After.

Authorizations:
sessionCookieapiToken
path Parameters
connection_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Connection public_id.

query Parameters
team_id
string

Only this team.

q
string

Match on channel name.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Destinations

Destinations of all types, their checks, tests, previews, Secrets and Signing secret.

List destinations

All types, with health. Outgoing webhook URL and header templates are shown with Secret references only.

Authorizations:
sessionCookieapiToken
query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

type
string (DestinationType)
Enum: "mattermost" "telegram" "webhook" "bridge"

Filter by type.

health
string (HealthState)
Enum: "healthy" "broken"

Filter by health.

route
string

Only Destinations of this Route (public_id).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Create Destination

type selects Mattermost, Telegram, outgoing webhook or Bridge. Saving a Mattermost, Telegram or Bridge Destination runs the Destination check through the interactive path and refuses one that fails it with 422 validation-failed and destination_check_failed. Creating an outgoing webhook Destination also generates its Signing secret, returned once in signing_secret (null for the other types). Routes attach Destinations through destination_ids.

Authorizations:
(sessionCookiecsrf) apiToken
Request Body schema: application/json
required
type
required
string
name
required
string non-empty
connection_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...

Opaque public identifier (public_id): a type prefix of one or two letters followed by 12 random characters of Crockford base32 (0–9 and A–Z without I, L, O and U; 60 bits), such as AGK7M3QX9P2RTA for an Alert Group. Prefixes use the same letters and differ per type: AG Alert Group, AE Audit log entry, AK Account link, AR Account link request, CN Connection, CR check run, DE delivery event, DS Destination, KR Link rule, NE Note, NK Integration token, NT Integration, PT Personal access token, RG Organization, RQ record of the Request log, RT Route, SA Service account, SN session, SR User, SS Stored Snapshot, ST Service account token, TB Lookup table, TE Timeline entry. Responses always carry the canonical upper-case form. Input is case-insensitive and normalized before lookup — O reads as 0, I and L as 1 — so the pattern also admits lower case and those letters. People refer to Alert Groups by #N, never by public_id.

team_id
required
string
channel_id
required
string
required
object (MentionSettings)

Keyed by the Mention names of Loud events. Reminders and auto-unacknowledge always mention the Owner, Takeovers the previous Owner.

required
object (Limiter)

A rate limit of limit calls per per_seconds.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "mattermost",
  • "name": "string",
  • "connection_id": "AGK7M3QX9P2RTA",
  • "team_id": "string",
  • "channel_id": "string",
  • "mentions": {
    },
  • "limiter": {
    }
}

Response samples

Content type
application/json
{
  • "destination": {
    },
  • "signing_secret": "string"
}

Read Destination

Authorizations:
sessionCookieapiToken
path Parameters
destination_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Destination public_id.

Responses

Response samples

Content type
application/json
Example
{
  • "type": "mattermost",
  • "name": "string",
  • "connection_id": "AGK7M3QX9P2RTA",
  • "team_id": "string",
  • "channel_id": "string",
  • "mentions": {
    },
  • "limiter": {
    },
  • "id": "AGK7M3QX9P2RTA",
  • "health": {
    },
  • "routes": [
    ],
  • "template_error": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string",
  • "team_name": "string",
  • "channel_name": "string"
}

Update Destination

Replaces the writable fields. Requires If-Match; a stale ETag gets 412. An omitted optional field keeps its stored value; an explicit null clears a nullable one. An omitted Secret field keeps the stored Secret. null on a proxy password clears it. Saving a Mattermost, Telegram or Bridge Destination runs the Destination check as createDestination does and refuses a failing one with destination_check_failed.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
destination_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Destination public_id.

header Parameters
If-Match
required
string

ETag of the representation being replaced, as returned by the last read. A mismatch gets 412; a missing header gets 428.

Request Body schema: application/json
required
type
required
string
name
required
string non-empty
connection_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...

Opaque public identifier (public_id): a type prefix of one or two letters followed by 12 random characters of Crockford base32 (0–9 and A–Z without I, L, O and U; 60 bits), such as AGK7M3QX9P2RTA for an Alert Group. Prefixes use the same letters and differ per type: AG Alert Group, AE Audit log entry, AK Account link, AR Account link request, CN Connection, CR check run, DE delivery event, DS Destination, KR Link rule, NE Note, NK Integration token, NT Integration, PT Personal access token, RG Organization, RQ record of the Request log, RT Route, SA Service account, SN session, SR User, SS Stored Snapshot, ST Service account token, TB Lookup table, TE Timeline entry. Responses always carry the canonical upper-case form. Input is case-insensitive and normalized before lookup — O reads as 0, I and L as 1 — so the pattern also admits lower case and those letters. People refer to Alert Groups by #N, never by public_id.

team_id
required
string
channel_id
required
string
required
object (MentionSettings)

Keyed by the Mention names of Loud events. Reminders and auto-unacknowledge always mention the Owner, Takeovers the previous Owner.

required
object (Limiter)

A rate limit of limit calls per per_seconds.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "mattermost",
  • "name": "string",
  • "connection_id": "AGK7M3QX9P2RTA",
  • "team_id": "string",
  • "channel_id": "string",
  • "mentions": {
    },
  • "limiter": {
    }
}

Response samples

Content type
application/json
Example
{
  • "type": "mattermost",
  • "name": "string",
  • "connection_id": "AGK7M3QX9P2RTA",
  • "team_id": "string",
  • "channel_id": "string",
  • "mentions": {
    },
  • "limiter": {
    },
  • "id": "AGK7M3QX9P2RTA",
  • "health": {
    },
  • "routes": [
    ],
  • "template_error": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string",
  • "team_name": "string",
  • "channel_name": "string"
}

Delete Destination

Always allowed: the Destination leaves every Route, and open Root messages get one final edit "No longer updated here" and nothing after; then the Destination's secrets are wiped. An outgoing webhook in events mode has no Root message: its queued events are abandoned and end as Not delivered, no final event is sent, and its secrets are wiped at once (in mode both, after the final edits of the template mode). It is a soft delete: the Destination is kept for history and no longer counts as using its Connection. There is no 409; a stale If-Match is 412.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
destination_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Destination public_id.

header Parameters
If-Match
string

Optional ETag; when present and stale, the request gets 412.

Responses

Response samples

Content type
application/problem+json
Example
{}

Run the Destination check

Verifies that Muster can still reach and post to the Destination without sending a message: Mattermost token and channel membership; Telegram getChat for the channel, its discussion group from linked_chat_id, and getChatMember for the bot in both; Bridge checkChannel. A success ends the Broken state. Not available for outgoing webhooks (422 with check_not_supported). Runs on the interactive path: when no limiter token is free within delivery.interactive_budget, the answer is 503 with Retry-After.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
destination_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Destination public_id.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "checks": [
    ],
  • "health": {
    },
  • "request_log_run": "AGK7M3QX9P2RTA"
}

Send a test message

One "create" request marked "Test message", built from a recent Alert Group of one of the Destination's Routes or from a built-in example, through the interactive path. An outgoing webhook sends the test event in events mode and the "create" request in template mode, both when it uses both. Secrets and the Signing secret are masked in the result. Test messages are never reconciled and change no Alert Group. A successful test of a Broken Destination ends the Broken state. Audited. A step that could not get a limiter token in time ends with error_class limited. A Bridge Destination posts one test message of the kind test with postMessage.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
destination_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Destination public_id.

Request Body schema: application/json
required
required
object (TestSource)

Responses

Request samples

Content type
application/json
{
  • "source": {
    }
}

Response samples

Content type
application/json
{
  • "steps": [
    ],
  • "health": {
    },
  • "request_log_run": "AGK7M3QX9P2RTA"
}

Preview a message or request

Renders the Root message or the webhook requests for a chosen Alert Group or the example without sending anything. For a Bridge Destination the item message is the envelope as Muster would post it, as JSON (format json).

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
destination_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Destination public_id.

Request Body schema: application/json
required
required
object (TestSource)

Responses

Request samples

Content type
application/json
{
  • "source": {
    }
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List the Secrets of a webhook Destination

Names with set and the time of the last change. Values are never returned. 409 (not_webhook_destination) for a Destination that is not an outgoing webhook.

Authorizations:
sessionCookieapiToken
path Parameters
destination_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Destination public_id.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Set a Secret of a webhook Destination

Creates or replaces the named Secret, referenced as {{ .Secrets.<name> }}. If-Match, when given, is compared with the ETag of listDestinationSecrets.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
destination_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Destination public_id.

secret_name
required
string^[A-Za-z_][A-Za-z0-9_]*$

Name of a Destination Secret.

header Parameters
If-Match
string

Optional ETag; when present and stale, the request gets 412.

Request Body schema: application/json
required
value
required
string

Write-only Secret.

Responses

Request samples

Content type
application/json
{
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "set": true,
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a Secret of a webhook Destination

If-Match, when given, is compared with the ETag of listDestinationSecrets.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
destination_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Destination public_id.

secret_name
required
string^[A-Za-z_][A-Za-z0-9_]*$

Name of a Destination Secret.

header Parameters
If-Match
string

Optional ETag; when present and stale, the request gets 412.

Responses

Response samples

Content type
application/problem+json
Example
{}

Read the Signing secret status

409 (not_webhook_destination) for a Destination that is not an outgoing webhook.

Authorizations:
sessionCookieapiToken
path Parameters
destination_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Destination public_id.

Responses

Response samples

Content type
application/json
{
  • "set": true,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "previous_active_since": "2019-08-24T14:15:22Z"
}

Regenerate the Signing secret

The first Signing secret is generated when the Destination is created. This returns a new one, once; requests then carry signatures with both the new and the previous secret until retirePreviousSigningSecret.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
destination_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Destination public_id.

Responses

Response samples

Content type
application/json
{
  • "secret": "string",
  • "status": {
    }
}

Retire the previous Signing secret

409 (not_webhook_destination) for a Destination that is not an outgoing webhook.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
destination_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Destination public_id.

Responses

Response samples

Content type
application/problem+json
Example
{}

List lookuptables

Authorizations:
sessionCookieapiToken
query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Create LookupTable

Authorizations:
(sessionCookiecsrf) apiToken
Request Body schema: application/json
required
name
required
string non-empty

Unique in the Organization; Link rule templates call lookup with it.

description
string
columns
required
Array of strings non-empty unique [ items non-empty ]

Column names, unique within the table.

required
Array of objects (LookupEntry)

Rows. The keys of values must be exactly columns (422 otherwise).

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "columns": [
    ],
  • "entries": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "columns": [
    ],
  • "entries": [
    ],
  • "id": "AGK7M3QX9P2RTA",
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Read LookupTable

Authorizations:
sessionCookieapiToken
path Parameters
lookup_table_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Lookup table public_id.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "columns": [
    ],
  • "entries": [
    ],
  • "id": "AGK7M3QX9P2RTA",
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Update LookupTable

Replaces the writable fields. Requires If-Match; a stale ETag gets 412. An omitted optional field keeps its stored value; an explicit null clears a nullable one. A new name for a table that the URL template of a Link rule reads by its name is refused with 409 (in_use), link_rules naming the rules, since they would read nothing.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
lookup_table_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Lookup table public_id.

header Parameters
If-Match
required
string

ETag of the representation being replaced, as returned by the last read. A mismatch gets 412; a missing header gets 428.

Request Body schema: application/json
required
name
required
string non-empty

Unique in the Organization; Link rule templates call lookup with it.

description
string
columns
required
Array of strings non-empty unique [ items non-empty ]

Column names, unique within the table.

required
Array of objects (LookupEntry)

Rows. The keys of values must be exactly columns (422 otherwise).

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "columns": [
    ],
  • "entries": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "columns": [
    ],
  • "entries": [
    ],
  • "id": "AGK7M3QX9P2RTA",
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Delete LookupTable

Refused with 409 (in_use) while the URL template of a Link rule reads the table by its name, link_rules naming the rules.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
lookup_table_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Lookup table public_id.

header Parameters
If-Match
string

Optional ETag; when present and stale, the request gets 412.

Responses

Response samples

Content type
application/problem+json
Example
{}

List linkrules

Authorizations:
sessionCookieapiToken
query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Create LinkRule

Authorizations:
(sessionCookiecsrf) apiToken
Request Body schema: application/json
required
name
required
string non-empty
required
Array of objects (Matcher)
required
object (LinkRuleScope)
url_template
required
string

Go template that may call lookup table key column.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "matchers": [
    ],
  • "scope": {
    },
  • "url_template": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "matchers": [
    ],
  • "scope": {
    },
  • "url_template": "string",
  • "id": "AGK7M3QX9P2RTA",
  • "builtin": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Read LinkRule

Authorizations:
sessionCookieapiToken
path Parameters
link_rule_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Link rule public_id.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "matchers": [
    ],
  • "scope": {
    },
  • "url_template": "string",
  • "id": "AGK7M3QX9P2RTA",
  • "builtin": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Update LinkRule

Replaces the writable fields. Requires If-Match; a stale ETag gets 412. An omitted optional field keeps its stored value; an explicit null clears a nullable one.

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
link_rule_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Link rule public_id.

header Parameters
If-Match
required
string

ETag of the representation being replaced, as returned by the last read. A mismatch gets 412; a missing header gets 428.

Request Body schema: application/json
required
name
required
string non-empty
required
Array of objects (Matcher)
required
object (LinkRuleScope)
url_template
required
string

Go template that may call lookup table key column.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "matchers": [
    ],
  • "scope": {
    },
  • "url_template": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "matchers": [
    ],
  • "scope": {
    },
  • "url_template": "string",
  • "id": "AGK7M3QX9P2RTA",
  • "builtin": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Delete LinkRule

The built-in "Explore" rule cannot be deleted (409).

Authorizations:
(sessionCookiecsrf) apiToken
path Parameters
link_rule_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Link rule public_id.

header Parameters
If-Match
string

Optional ETag; when present and stale, the request gets 412.

Responses

Response samples

Content type
application/problem+json
Example
{}

Templates

Template preview and dry run.

Render a template against a sample

Parses and renders a template in the sandbox against a recent Stored Snapshot, an Alert Group or a built-in example. Template errors are returned in errors with their position, not as a Problem, so an editor can show them next to the preview.

Authorizations:
(sessionCookiecsrf) apiToken
Request Body schema: application/json
required
kind
required
string (TemplateKind)
Enum: "root_message" "line" "ack_timeout_notice" "link_rule" "webhook_request"
template
required
string

The template to render; empty renders what a Route without a template of the kind shows, and the result returns the source of the built-in template.

format
string or null
Enum: "markdown" "html" "commonmark" null

The markup the output is laid out in and alert data are escaped for — markdown as in Mattermost (the default), html as in Telegram, commonmark as in a bridge's envelope body. Ignored for link_rule and webhook_request, which have no markup.

route_id
string or null (NullablePublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...

A public_id in the format of PublicId, or null.

stored_snapshot_id
string or null

A recent Stored Snapshot as the sample. Without a sample the most recent ones the Route took are used (template.dry_run_sample), or a built-in example.

alert_group_id
string or null (NullablePublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...

A public_id in the format of PublicId, or null.

language
string or null (NullableLanguage)
Enum: "en" "ru" null

UI or template language; null follows the default.

length_limit
integer or null >= 1

Messenger length limit to apply, for example 4096.

Responses

Request samples

Content type
application/json
{
  • "kind": "root_message",
  • "template": "string",
  • "format": "markdown",
  • "route_id": "AGK7M3QX9P2RTA",
  • "stored_snapshot_id": "string",
  • "alert_group_id": "AGK7M3QX9P2RTA",
  • "language": "en",
  • "length_limit": 1
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "output": "string",
  • "truncated": true,
  • "format": "markdown",
  • "source": "string",
  • "sample": "stored_snapshot",
  • "errors": [
    ]
}

List the Connections an account can be linked through

The profile's own short list of the Connections that are not deleted, for picking one when linking a messenger account. It needs no Permission, independently of connections:read, and shows only the id, the name and the messenger of each Connection, and for a Bridge Connection how an account can be linked through it — link_methods and handle_kind, from the Connection's last info. Service account tokens get 403 (service_account_not_allowed).

Authorizations:
sessionCookieapiToken

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Request log

The recent HTTP requests Muster sent for a Connection or an outgoing webhook Destination, each attempt with its answer and masked, kept for request_log.max_age and to the newest request_log.max_records of each owner (C-23).

List the Request log of a Connection, a Destination or a check run

The records of exactly one owner, or of one check run, newest first: connection lists every record of a Connection, destination every record of an outgoing webhook Destination or, for a messenger Destination, the records of its Connection that name it; run alone lists the records of that check run whose owner is a Connection or nobody — the checks before saving of new Connections — and beside an owner it narrows that owner's list. Neither an owner nor a run, or both owners, answer 422 with the code one_of_required. The caller needs connections:read to name a Connection or a run alone and destinations:read to name a Destination (403 otherwise); an unknown or deleted owner is 404. Only records newer than request_log.max_age and among the newest request_log.max_records of their owner are listed — a messenger Destination's within its Connection's — so a list never shows more than that bound. Each record is one attempt of a request: its URL as errors show it, its status, latency and path, without headers or bodies, which getRequestRecord reads.

Authorizations:
sessionCookieapiToken
query Parameters
cursor
string

Opaque cursor from next_cursor of the previous page. Offsets are not supported.

limit
integer [ 1 .. 500 ]
Default: 50

Page size (api.page_size).

connection
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: connection=AGK7M3QX9P2RTA

The Connection whose records are listed, by public_id.

destination
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: destination=AGK7M3QX9P2RTA

The Destination whose records are listed, by public_id.

direction
string (RequestDirection)
Enum: "outbound" "inbound"

Only the requests Muster sent (outbound) or received (inbound).

status_class
string
Enum: "2xx" "3xx" "4xx" "5xx" "none"

Only the records whose answer has a status of this class, or, with none, those that got no answer.

operation
string [ 1 .. 64 ] characters

Only the records of this operation, such as createPost, getUpdates, pollEvents or event.

alert_group
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: alert_group=AGK7M3QX9P2RTA

Only the records of the deliveries of this Alert Group, by public_id.

run
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: run=AGK7M3QX9P2RTA

Only the records of this check run (CR…), which the results of checkConnection, checkConnectionDraft, checkDestination and testDestination name as request_log_run. Alone it lists the records of the run whose owner is a Connection or nobody and needs connections:read; the records of an outgoing webhook's test or probe are listed beside its destination. A run that left no record, or an id that is no check run, lists nothing.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Read a record of the Request log

One record with its headers and bodies, masked. The caller needs the Permission of the record's owner, connections:read for a Connection's record — even one listed through a messenger Destination with destinations:read — and destinations:read for an outgoing webhook's (403 otherwise). A record past request_log.max_age or past the newest request_log.max_records of its owner, or whose owner is deleted, is 404, as it is in no list. Headers, bodies and the error are untrusted text.

Authorizations:
sessionCookieapiToken
path Parameters
request_record_id
required
string (PublicId) ^[A-HJKMNP-TV-Za-hjkmnp-tv-z]{1,2}[0-9A-TV-Za...
Example: AGK7M3QX9P2RTA

Record of the Request log, by public_id.

Responses

Response samples

Content type
application/json
{
  • "id": "AGK7M3QX9P2RTA",
  • "at": "2019-08-24T14:15:22Z",
  • "direction": "outbound",
  • "operation": "string",
  • "method": "string",
  • "url": "string",
  • "status": 0,
  • "latency_ms": 0,
  • "via": "direct",
  • "attempt": 1,
  • "error_class": "retry_after",
  • "error_code": "dns_failed",
  • "check": "connection_check",
  • "check_run": "AGK7M3QX9P2RTA",
  • "connection_id": "AGK7M3QX9P2RTA",
  • "destination": {
    },
  • "alert_group": {
    },
  • "request_body_truncated": true,
  • "response_body_truncated": true,
  • "request_headers": {
    },
  • "request_body": "string",
  • "request_body_bytes": 0,
  • "response_headers": {
    },
  • "response_body": "string",
  • "response_body_bytes": 0,
  • "error": "string"
}

System

System status, notices and the served specification.

List active Organization-wide notices

"Recovering after downtime" for every signed-in user, "no replica is leading" for Admins. Changes arrive as system-notices hints.

Authorizations:
sessionCookieapiToken

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Read the System status

Read-only: replicas and the Leader with their key ids, the recovery state, delivery queues, Broken Destinations, Integrations with Heartbeat lost or truncated Snapshots, template errors, active Storms and the last outgoing heartbeat.

Authorizations:
sessionCookieapiToken

Responses

Response samples

Content type
application/json
{
  • "version": "string",
  • "commit": "string",
  • "replicas": [
    ],
  • "recovery": {
    },
  • "delivery_queues": [
    ],
  • "broken_destinations": [
    ],
  • "integrations_attention": [
    ],
  • "template_errors": [
    ],
  • "active_storms": [
    ],
  • "outgoing_heartbeat": {
    }
}

Read this specification

The specification the binary was built from, as checked in at api/openapi.yaml.

Responses

Health and metrics

Liveness, readiness and metrics on the internal listener. Hand-written handlers: excluded from the generated server.

Liveness

Performs no checks.

Responses

Readiness

Checks only the database.

Responses

Prometheus metrics

Pull only. The metric catalogue is generated from the registry in code; no JSON catalogue is served.

Responses

Outgoing webhooks

The events-mode request Muster sends to outgoing webhook Destinations.

Events-mode request to an outgoing webhook Destination Webhook

Sent by Muster to the URL of an outgoing webhook Destination in events mode: one POST per lifecycle event, in order per Alert Group, at least once. Every request carries webhook-id, webhook-timestamp and webhook-signature in the style of the Standard Webhooks specification: the signature is v1,<base64 HMAC-SHA256> over <webhook-id>.<webhook-timestamp>.<body>, with several space-separated signatures while a previous Signing secret is not yet retired. Receivers drop duplicates by webhook-id. Response mapping: 2xx delivered; 429 or 503 with Retry-After retried exactly as asked; 408, other 5xx, timeouts and network errors retried with backoff; 401, 403, 404 and 410 mark the Destination Broken; 400, 413, 422, redirects and everything else end that delivery as Not delivered.

Authorizations:
sessionCookieapiToken
header Parameters
webhook-id
required
string

Id of this event, kept across retries.

webhook-timestamp
required
string

Unix time in seconds when the request was signed.

webhook-signature
required
string

One or more space-separated v1,<base64> signatures.

Request Body schema: application/json
required
version
required
integer
Value: 1
event
required
string (WebhookEventName)
Enum: "created" "alerts_added" "alert_replaced" "alert_resolved" "alert_continued" "annotations_changed" "severity_raised" "urgency_raised" "reopened" "snooze_ended" "resolved" "moved_to_default_route" "acknowledged" "takeover" "unacknowledged" "unresolved" "snoozed" "unsnoozed" "note_added" "ack_timeout" "unclaimed" "reminder" "reminder_answered" "auto_unacknowledged" "notices_missed" "test"

One of the lifecycle event names (see LifecycleEvent) or test, which only a Destination test sends. New names are added within version 1; receivers ignore names they do not know.

notify
required
boolean

True exactly when the event is Loud.

required
Array of objects (WebhookMentionTarget)
sequence
required
integer >= 0

The lifecycle event number of the Alert Group, kept across retries. It grows with every lifecycle event of the Alert Group but may have gaps, and for a Destination added to the Route later it does not start at 1; receivers rely only on "greater means newer". 0 on the test event.

occurred_at
required
string <date-time>
required
object (WebhookActor)
required
object (WebhookAlertGroup)

The current state of the Alert Group when the event was recorded.

required
Array of objects (WebhookAlert)

One element per Alert, by fingerprint.

test
boolean

True only on the test event, which carries an example or recent Alert Group and belongs to no Alert Group's order.

Responses

Request samples

Content type
application/json
Example
{
  • "version": 1,
  • "event": "created",
  • "notify": true,
  • "mentions": [
    ],
  • "sequence": 1,
  • "occurred_at": "2026-10-03T09:41:07Z",
  • "actor": {
    },
  • "alert_group": {
    },
  • "alerts": [
    ]
}