Reference & migration

MonoDuty REST API Reference

Use scoped, short-lived customer API tokens with the explicit v1 allowlist for incidents, services, and Monitors.

Customer API v1

The customer API is a deliberately small bearer-token allowlist for workspace automation. It currently exposes incident reads and lifecycle writes plus read-only service and Monitor endpoints. Dashboard-only administration, Heartbeats, schedules, members, billing, and arbitrary internal /api routes are not part of this token contract. Public alert ingestion uses the separate mndty.com endpoint shown below.

Base URL

https://api.monoduty.com/api/v1

Every route is nested under the exact token workspace: /organizations/{organization}. Successful resource responses use a data envelope. Error HTTP statuses are part of the route contract and responses include a human-readable message; documented domain conflicts also include their listed code. Clients must not assume every framework validation or authorization response has a machine-readable code.

Authentication and token lifecycle

The dashboard authenticates with a Secure, HttpOnly, host-only server session cookie. Browser JavaScript cannot read that credential. State-changing dashboard requests also send a short-lived CSRF synchronizer value. Never copy browser cookies or CSRF values into a script.

A Billing Owner or Account Admin can always list or revoke token metadata for cleanup. Creating a new token additionally requires the workspace API-access entitlement. Open Settings → API tokens and complete a fresh password, authenticator, or recovery-code check. Choose READ_ONLY for list/detail calls or READ_WRITE when incident creation and lifecycle transitions are required. Tokens expire after at most 30 days. The plaintext is returned once at creation; later lists contain metadata only. Expired or revoked tokens stop authorizing requests.

Have a secret manager inject the environment variable, or use the no-echo prompt below before an example and unset it immediately afterwards.

read -rsp 'MonoDuty API token: ' MONODUTY_API_TOKEN; printf '
'
curl --fail-with-body \
  -H "Authorization: Bearer $MONODUTY_API_TOKEN" \
  -H "Accept: application/json" \
  https://api.monoduty.com/api/v1/organizations/YOUR_WORKSPACE_ID/incidents
unset MONODUTY_API_TOKEN

Keep the token in a secret manager. Do not put it in a URL, query string, source repository, browser localStorage/sessionStorage, analytics, screenshots, or application logs. The no-echo prompt avoids shell history; use a secret manager in CI. Public alert senders use a service-specific Webhook token instead.

Webhook ingestion

Each explicit source exposes a revocable ingestion URL. It accepts the native MonoDuty JSON contract and does not require a management bearer token.

POST https://mndty.com/YOUR_WEBHOOK_TOKEN

curl -X POST https://mndty.com/YOUR_WEBHOOK_TOKEN \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cpu-high-001" \
  -d '{"title":"CPU High","severity":"critical"}'

Rotate a token from the owning service when it has been exposed. Team Managers may manage sources only for services owned by their team.

Services API

A service has one owning team and supplies the routing boundary for alert sources. Customer tokens expose read-only service inventory:

GET /organizations/:organization_id/services

GET /organizations/:organization_id/services/:service_id

curl --fail-with-body \
  -H "Authorization: Bearer $MONODUTY_API_TOKEN" \
  -H "Accept: application/json" \
  https://api.monoduty.com/api/v1/organizations/YOUR_WORKSPACE_ID/services

Service create, update, and delete remain dashboard browser-session operations and are not accepted by the customer API token allowlist.

Send an event

POST https://mndty.com/YOUR_WEBHOOK_TOKEN

Send at least one of title or message. Optional fields include severity, description, dedup_key, source, and metadata.

Prefer an Idempotency-Key header. Same key and same payload returns HTTP 200 with duplicate: true; the same key with a different payload returns HTTP 409 with code idempotency_conflict. Replays never update an incident.

Incidents API

READ_ONLY and READ_WRITE tokens may use the two GET routes. The remaining routes require READ_WRITE.

GET /organizations/:organization_id/incidents

GET /organizations/:organization_id/incidents/:incident_id

POST /organizations/:organization_id/incidents

POST /organizations/:organization_id/incidents/:incident_id/acknowledge

POST /organizations/:organization_id/incidents/:incident_id/investigate

POST /organizations/:organization_id/incidents/:incident_id/resolve

POST /organizations/:organization_id/incidents/:incident_id/close

POST /organizations/:organization_id/incidents/:incident_id/reopen

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $MONODUTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  https://api.monoduty.com/api/v1/organizations/YOUR_WORKSPACE_ID/incidents \
  -d '{"title":"Controlled API drill","description":"Created by the documented v1 contract","severity":"LOW","owning_team_id":"YOUR_TEAM_UUID"}'

The API rechecks token expiry and status, account verification, Account Admin/Billing Owner membership, API entitlement, and the exact workspace on every request. A token cannot cross into another workspace by changing the URL.

Monitors API

Customer tokens expose Monitor inventory through read-only routes:

GET /organizations/:organization_id/monitors

GET /organizations/:organization_id/monitors/:monitor_id

Monitor mutations and all Heartbeat management remain dashboard browser-session operations; they are not in the customer API v1 allowlist. A Heartbeat's public check-in URL still uses https://mndty.com/ping/:token and is a separate ingestion credential.