Incidents

Ingest an alert

POST/v1/alertsrequires incidents:ingest

Accepts an authenticated alert into a persisted incident with durable dispatch intent. Production paging remains behind activation gates; test incidents record simulated notification attempts and never call a delivery provider. Configuration and escalation-policy IDs must belong to the API key's workspace. Test keys use a separate incident namespace. Distinct events with the same alias, configuration and policy join the active incident until it is resolved; acknowledgment is preserved. The incident title and severity retain the first alert's values. Resolution releases the alias for a new incident.

Supply a unique Idempotency-Key of 1–255 non-space printable ASCII characters for each event; reuse it only for an exact retry. Matching retries return the original acceptance body, even after resolution, with Idempotency-Replayed: true. Different normalized payloads with the same key return 409. Receipts have no automatic expiration. The body is limited to 16 KiB. Use source-prefixed aliases to avoid grouping unrelated integrations.

Requestcurl -X POST https://api.transmit.dev/v1/alerts \
  -H "Authorization: Bearer tr_v2_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
       "configurationId": "00000000-0000-4000-8000-000000000001",
       "escalationPolicyId": "00000000-0000-4000-8000-000000000002",
       "alias": "monitoring:database-primary",
       "title": "Database unavailable",
       "severity": "critical"
     }'

Parameters

Name	In	Notes
`Idempotency-Key` required	header	A unique key, at most 255 characters. Replaying it returns the original result instead of billing twice.

Body

Field	Type	Notes
`configurationId` required	`string`	uuid
`escalationPolicyId` required	`string`	uuid
`alias` required	`string`	1–128 characters
`title` required	`string`	1–200 characters
`description`	`string`	at most 4000 characters. defaults to ""
`severity`	`"critical" \| "high" \| "medium" \| "low"`	defaults to "high"

Responses

Status	Meaning
`202`	Persisted acceptance receipt and durable dispatch intent; production paging remains gated
`400`	Invalid or missing idempotency key
`401`	The API key is missing, malformed, expired or revoked
`403`	The API key lacks the `incidents:ingest` scope
`404`	Configuration or policy not found in this workspace
`409`	Idempotency key conflicts with a different payload
`413`	Body exceeds 16 KiB
`415`	Content-Type must be application/json
`422`	Invalid alert payload

Every response body is described in the OpenAPI spec, which this page is generated from.