Alerts

Create alert status

Create a custom alert status with a display name and colour.

POST/alerts/statuses

Create a custom alert status with a display name and colour. Statuses are per organization and can be used when updating an alert’s status.

Enterprise authentication

Send these requests to https://api.cloud.blnkfinance.com on Blnk Cloud. On a self-hosted Enterprise deployment, send them to ENTERPRISE_PUBLIC_URL.

Pass an Enterprise API key, or an OAuth access token, in the X-blnk-key header. Create the key in Enterprise API keys, or issue a token with Enterprise OAuth.

This credential comes from the Cloud or Enterprise workspace. A Core API key belongs to the Core instance.

X-blnk-keystringrequiredheader

Enterprise API key, or an OAuth access token.

Body

namestringrequiredbody

Display name for the status (e.g. “Pending Review”, “In Progress”). If key is omitted, a key is derived from this (e.g. “Pending Review” → PENDING_REVIEW). Names must be unique per org when key is auto-derived.

colourstringrequiredbody

Hex colour code for the status. Must be one of the values in allowed_colours from the list statuses response.

keystringbody

Optional. Custom key for the status (e.g. PENDING_REVIEW). If omitted, a key is derived from name. Must be unique per organization.

Response

organization_idstring

Organization ID that owns the status.

keystring

The status key (supplied or derived from name).

namestring

Display name of the status.

colourstring

Hex colour code of the status.

created_attimestamp

ISO 8601 timestamp when the status was created.

updated_attimestamp

ISO 8601 timestamp when the status was last updated.

curl -X POST 'https://api.cloud.blnkfinance.com/alerts/statuses' \
  -H 'X-blnk-key: CLOUD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Pending Review",
    "colour": "#3B82F6"
  }'

{
  "organization_id": "org_01ABC123",
  "key": "PENDING_REVIEW",
  "name": "Pending Review",
  "colour": "#3B82F6",
  "created_at": "2025-01-29T14:00:00Z",
  "updated_at": "2025-01-29T14:00:00Z"
}

{
  "error": "Key: 'CreateStatusRequest.Name' Error:Field validation for 'Name' failed on the 'required' tag\nKey: 'CreateStatusRequest.Colour' Error:Field validation for 'Colour' failed on the 'required' tag"
}