curl --request POST \
  --url https://api.timbal.ai/orgs/{org_id}/alarms/{alarm_id}/channels \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "slack",
  "name": "oncall-pages",
  "config": {
    "token": "xoxb-1234567890123-1234567890123",
    "channel": "C0123456789"
  }
}
'

{
  "already_linked": true,
  "channel_id": 123
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

Alarms

Attach Channel to Alarm

Attach another notification channel to an alarm, so one condition reaches several destinations (page Slack and email the on-call, say).

Accepts the same channel shape as alarm creation: { "id": <channel id> } to reuse an existing channel, or inline type + config to create one. Inline channels identical to an existing row are deduped rather than duplicated.

Idempotent — re-attaching a channel that is already linked returns already_linked: true and changes nothing.

Gated by the alarm, not the channel: alarms.manage for an org-level alarm, projects.alarms.manage on the owner for a project alarm. Channels themselves are org-wide, so a project-scoped caller can point their alarm at any existing channel — attaching one is a routing decision about their alarm, whereas creating or deleting the channel row needs notification_channels.manage.

POST

orgs

{org_id}

alarms

{alarm_id}

channels

curl --request POST \
  --url https://api.timbal.ai/orgs/{org_id}/alarms/{alarm_id}/channels \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "slack",
  "name": "oncall-pages",
  "config": {
    "token": "xoxb-1234567890123-1234567890123",
    "channel": "C0123456789"
  }
}
'

{
  "already_linked": true,
  "channel_id": 123
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

Timbal API key. Obtain your API key from the Timbal platform settings. See Authentication for more information.

Path Parameters

org_id

string

required

alarm_id

string

required

Body

application/json

Channel reference embedded in another resource's create body (alarms). Either reuse by id, or supply type + config inline.

config

object

Omitted or null when linking by id only.

string | null

Existing NotificationChannels.id for this org. When set, type / config / name are ignored.

name

string | null

type

enum<string>

Available options:

email,

slack

Response

Channel attached

already_linked

boolean

required

true when this channel was already attached, so the call changed nothing. Linking is idempotent — retries must not create duplicates, which would notify the same destination twice per transition.

channel_action

enum<string>

required

How the underlying NotificationChannels row was resolved: referenced by id, deduped onto an identical existing row, or inserted.

Available options:

linked,

reused,

created

channel_id

integer<int64>

required

Alarm History Detach Channel from Alarm

API Documentation

Me

Organizations

Projects

Knowledge Bases

Evals

ACE

Alarms

Connectors

Attach Channel to Alarm

Authorizations

Path Parameters

Body

Response