Destinations API

Chirpier still uses /destinations in the HTTP route names, but conceptually these are reusable alert destinations.

Routes

POST /v1.0/destinations
GET /v1.0/destinations
GET /v1.0/destinations/:destinationID
PUT /v1.0/destinations/:destinationID
POST /v1.0/destinations/:destinationID/test

Destination object

In the current API shape, the destination provider type is carried in the channel field.


{
  "destination_id": "5e9d6fd1-727a-46f6-a377-6c8ef407efdc",
  "channel": "slack",
  "url": "https://hooks.slack.com/services/...",
  "credentials": null,
  "scope": "all",
  "policy_ids": [],
  "enabled": true,
  "created_at": "2026-04-08T18:30:00Z",
  "updated_at": "2026-04-08T18:30:00Z",
  "last_delivered_at": null,
  "last_error": null
}

Supported destination provider types

Channel	`url`	`credentials`
`slack`	Incoming webhook URL	Not needed
`discord`	Discord webhook URL	Not needed
`telegram`	Not needed	`{"bot_token": "...", "chat_id": "..."}`
`webhook`	Target endpoint URL	Optional `{"authorization": "Bearer ..."}`
`email`	Not needed	Not needed (uses Chirpier’s mailer)

Scope rules

Destinations can be constrained by:

scope
policy_ids

That scope is matched during alert delivery.

Current matching logic:

scope="all" matches every alert for the workspace
otherwise, a destination only matches when the alert policy_id is included in policy_ids

Create destination

Raw API


curl -X POST "https://api.chirpier.co/v1.0/destinations" \
  -H "Authorization: Bearer $CHIRPIER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "slack",
    "url": "https://hooks.slack.com/services/T000/B000/secret",
    "scope": "all",
    "policy_ids": [],
    "enabled": true
  }'

JavaScript


const destination = await client.createDestination({
  channel: "slack",
  url: "https://hooks.slack.com/services/T000/B000/secret",
  scope: "all",
  policy_ids: [],
  enabled: true,
});

Python


destination = client.create_destination(
    {
        "channel": "slack",
        "url": "https://hooks.slack.com/services/T000/B000/secret",
        "scope": "all",
        "policy_ids": [],
        "enabled": True,
    }
)

Go


destination, err := client.CreateDestination(ctx, chirpier.Destination{
    Channel:   "slack",
    URL:       "https://hooks.slack.com/services/T000/B000/secret",
    Scope:     "all",
    PolicyIDs: []string{},
    Enabled:   true,
})

If the destination configuration is invalid, the API returns 400.

Read, update, and test

GET /v1.0/destinations returns all destinations for the current user
GET /v1.0/destinations/:destinationID reads one destination
PUT /v1.0/destinations/:destinationID updates an existing destination
POST /v1.0/destinations/:destinationID/test sends a test notification and returns the synthetic test alert_id on success

Testing returns:

200 OK with:


{
  "alert_id": "414d5d9c-b8c0-4e8b-bf3a-0d4e3e616604",
  "destination_id": "5e9d6fd1-727a-46f6-a377-6c8ef407efdc",
  "status": "sent"
}

404 Not Found if the destination is missing
502 Bad Gateway if the downstream provider rejects the test send

Pair destination tests with GET /v1.0/alerts/:alertID/deliveries?kind=test using the returned alert_id when debugging delivery behavior.

Raw API


TEST_ALERT_ID=$(curl -s -X POST "https://api.chirpier.co/v1.0/destinations/$DESTINATION_ID/test" \
  -H "Authorization: Bearer $CHIRPIER_TOKEN" | jq -r '.alert_id')
 
curl -G "https://api.chirpier.co/v1.0/alerts/$TEST_ALERT_ID/deliveries" \
  -H "Authorization: Bearer $CHIRPIER_TOKEN" \
  --data-urlencode "kind=test"

JavaScript


const test = await client.testDestination(DESTINATION_ID);
const deliveries = await client.getAlertDeliveries(test.alert_id, { kind: "test" });

Python


test = client.test_destination(DESTINATION_ID)
deliveries = client.get_alert_deliveries(test["alert_id"], kind="test")

Go


test, err := client.TestDestination(ctx, DESTINATION_ID)
deliveries, err := client.GetAlertDeliveries(ctx, test.AlertID, 0, 0, "test")