Alerts

Server

Download schema

System notifications and warnings

List alerts

GET

https://common-api.karma.life

/api/v1/alerts

List alerts with optional filtering

Permissions: 🔵 alerts.read

List alerts › query Parameters

locationId

number

Filter by location ID

severity

string · enum

Filter by severity

Enum values:

info

warning

error

critical

status

string · enum

Filter by status

Enum values:

active

acknowledged

resolved

alertType

string

Filter by alert type

page

number · min: 1

Page number

Default: 1

limit

number · min: 1 · max: 100

Items per page

Default: 20

List alerts › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

Get alert

GET

https://common-api.karma.life

/api/v1/alerts/{id}

Get a single alert by ID

Permissions: 🔵 alerts.read

Get alert › path Parameters

id

string · uuid · required

Alert ID (UUID)

Get alert › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

Update alert status

PATCH

https://common-api.karma.life

/api/v1/alerts/{id}

Update alert status (acknowledge or resolve)

Permissions: 🟠 alerts.update

Update alert status › path Parameters

id

string · uuid · required

Alert ID (UUID)

Update alert status › Request Body

status

string · enum · required

New status (cannot reopen once resolved)

Enum values:

acknowledged

resolved

Update alert status › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

Emit alert.created event

POST

https://common-api.karma.life

/internal/alerts/{id}/emit

Emit alert.created Ably event for an existing alert (internal use only — called by printer-service)

Emit alert.created event › path Parameters

id

string · uuid · required

Alert ID (UUID)

Emit alert.created event › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

Webhook: Alert created

POST

https://common-api.karma.life

/webhook/alert.created

Fired when a new alert is raised. The full Alert is spread into data. Typically emitted by external monitoring rather than common-api itself.

This is an outbound webhook event. Karma POSTs this payload to the URL you registered via POST /api/v1/webhooks/subscriptions. Your endpoint should respond 2xx within 30 seconds to acknowledge delivery.

Webhook: Alert created › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

alert.created

resource

string · enum · required

Enum values:

alert

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object · required

Webhook: Alert created › Responses

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

POST/webhook/alert.created

curl --request POST \
  --url https://common-api.karma.life/webhook/alert.created \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "evt_01HZK3...",
  "event": "alert.created",
  "resource": "alert",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "locationId": 0,
    "alertType": "alertType",
    "severity": "info",
    "title": "title",
    "message": "message",
    "details": {},
    "stackTrace": "stackTrace",
    "context": {},
    "latestStatus": "active",
    "resolvedAt": "2024-08-25T15:00:00Z",
    "resolvedBy": 0,
    "acknowledgedAt": "2024-08-25T15:00:00Z",
    "acknowledgedBy": 0,
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}
'

Example Request Body

{
  "id": "evt_01HZK3...",
  "event": "alert.created",
  "resource": "alert",
  "resourceId": "resourceId",
  "timestamp": "2024-08-25T15:00:00Z",
  "apiVersion": "v1",
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "locationId": 0,
    "alertType": "alertType",
    "severity": "info",
    "title": "title",
    "message": "message",
    "details": {},
    "stackTrace": "stackTrace",
    "context": {},
    "latestStatus": "active",
    "resolvedAt": "2024-08-25T15:00:00Z",
    "resolvedBy": 0,
    "acknowledgedAt": "2024-08-25T15:00:00Z",
    "acknowledgedBy": 0,
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
}

json

Example Responses

No example specified for this content type

Webhook: Alert updated

POST

https://common-api.karma.life

/webhook/alert.updated

Fired on alert state changes (acknowledged, resolved). The full updated Alert is spread into data.

Webhook: Alert updated › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

alert.updated

resource

string · enum · required

Enum values:

alert

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object

Webhook: Alert updated › Responses

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

Analytics

List alerts

GET

https://common-api.karma.life

/api/v1/alerts

List alerts with optional filtering

Permissions: 🔵 alerts.read

List alerts › query Parameters

locationId

number

Filter by location ID

severity

string · enum

Filter by severity

Enum values:

info

warning

error

critical

status

string · enum

Filter by status

Enum values:

active

acknowledged

resolved

alertType

string

Filter by alert type

page

number · min: 1

Page number

Default: 1

limit

number · min: 1 · max: 100

Items per page

Default: 20

List alerts › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

Get alert

GET

https://common-api.karma.life

/api/v1/alerts/{id}

Get a single alert by ID

Permissions: 🔵 alerts.read

Get alert › path Parameters

id

string · uuid · required

Alert ID (UUID)

Get alert › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

Update alert status

PATCH

https://common-api.karma.life

/api/v1/alerts/{id}

Update alert status (acknowledge or resolve)

Permissions: 🟠 alerts.update

Update alert status › path Parameters

id

string · uuid · required

Alert ID (UUID)

Update alert status › Request Body

status

string · enum · required

New status (cannot reopen once resolved)

Enum values:

acknowledged

resolved

Update alert status › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

Emit alert.created event

POST

https://common-api.karma.life

/internal/alerts/{id}/emit

Emit alert.created Ably event for an existing alert (internal use only — called by printer-service)

Emit alert.created event › path Parameters

id

string · uuid · required

Alert ID (UUID)

Emit alert.created event › Responses

Default Response

status

string · enum · required

Enum values:

success

object · required

Webhook: Alert created

POST

https://common-api.karma.life

/webhook/alert.created

Fired when a new alert is raised. The full Alert is spread into data. Typically emitted by external monitoring rather than common-api itself.

Webhook: Alert created › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

alert.created

resource

string · enum · required

Enum values:

alert

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object · required

Webhook: Alert created › Responses

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned

Webhook: Alert updated

POST

https://common-api.karma.life

/webhook/alert.updated

Fired on alert state changes (acknowledged, resolved). The full updated Alert is spread into data.

Webhook: Alert updated › Request Body

Standard envelope wrapping every outbound webhook event.

id

string · required

Unique webhook delivery ID

event

string · enum · required

Enum values:

alert.updated

resource

string · enum · required

Enum values:

alert

resourceId

string · required

String ID of the affected resource

timestamp

string · date-time · required

ISO 8601 timestamp when the event was emitted

apiVersion

string · enum · required

Enum values:

object

Webhook: Alert updated › Responses

200

Acknowledged. Karma considers any 2xx response a successful delivery; non-2xx triggers retry with exponential backoff.

No data returned