alerts API · Marula PSA docs

API reference

7 operations in alerts. Raw spec: openapi.json.

GET/api/v1/alert-sources

GET /api/alert-sources — newest-first config list (no secrets).

Responses

Status	Description
`200`

Security: bearer

POST/api/v1/alert-sources

POST /api/alert-sources — creates an ingest source, generates + seals its HMAC secret (returned ONCE), and writes the audit trail. Instant-first (IF1/IF2): idempotency-keyed, read-your-write response.

Request body

CreateAlertSourceRequest

Responses

Status	Description
`200`
`409`	source_ref collision or idempotency key reused
`422`	validation failed

Security: bearer

PATCH/api/v1/alert-sources/{id}

PATCH /api/alert-sources/{id} — re-point the board, rename, resize the storm window, or disable. Instant-first (IF1/IF2).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

PatchAlertSourceRequest

Responses

Status	Description
`200`
`404`	source not visible in scope (rls_sparse)
`409`	version conflict or idempotency key reused
`422`	validation failed

Security: bearer

GET/api/v1/alerts

GET /api/alerts — newest-first ledger browse, filterable by source and incident ticket (staff, ticket-view scoped).

Parameters

Name	In	Type	Required	Description
`source_id`	query	—	No
`ticket_id`	query	—	No
`status`	query	—	No	Triage filter (0089): "open" \| "acknowledged" \| "resolved" — absent returns all states.
`limit`	query	integer	No
`offset`	query	integer	No

Responses

Status	Description
`200`

Security: bearer

POST/api/v1/alerts/ingest/{source_ref}

POST /api/alerts/ingest/{source_ref} — HMAC-verified alert ingest.

Responses: 200 with a terminal `status` (incident_created / collapsed / duplicate); 401 missing/bad signature; 403 disabled source; 404 unknown source_ref; 409 source is a generic M2M receiver (its profile emits envelopes, so the answer names `/api/webhooks/ingest/{source_ref}`); 422 malformed payload.

Parameters

Name	In	Type	Required	Description
`source_ref`	path	string	Yes	Public ingest routing id of an alert source

Request body

IngestAlertRequest

Responses

Status	Description
`200`
`401`	missing or invalid signature
`403`	alert source disabled
`404`	unknown source_ref
`422`	validation failed

POST/api/v1/alerts/{id}/acknowledge

POST /api/alerts/{id}/acknowledge — triage: open → acknowledged. Instant-first (IF1/IF2): idempotency-keyed, read-your-write. Re-ack (or ack of an already-resolved alert) is a typed conflict — the state is honest, never silently rewritten.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

MutationParams

Responses

Status	Description
`200`
`404`	alert not visible in scope
`409`	alert already acknowledged or resolved
`422`	validation failed

Security: bearer

POST/api/v1/alerts/{id}/resolve

POST /api/alerts/{id}/resolve — triage: open/acknowledged → resolved. Resolving straight from `open` leaves the ack fields NULL (no acknowledgement ever happened — the row renders that honestly).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

MutationParams

Responses

Status	Description
`200`
`404`	alert not visible in scope
`409`	alert already resolved
`422`	validation failed

Security: bearer