Alert destination
Package: agentrouter.alerting.v1 Service: AlertDestinationService
Endpoints
List alert destinations
What it does: Returns every destination for the workspace, newest first.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | yes | undocumented |
workspace_id | yes | undocumented |
Response fields:
| Field | Required | Description |
|---|---|---|
destinations | no | Destinations for the workspace, newest first. |
{"signatures":{"go":"c.AlertDestination().ListAlertDestinations(ctx, \u0026alertingv1.ListAlertDestinationsRequest{...})","python":"client.alertdestination.listalertdestinations(...)","typescript":"client.alertdestination.listalertdestinations({...})","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../dataplanes/01H.../alert-destinations\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"examples":{"go":"// No Go SDK wrapper for AlertDestinationService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for AlertDestinationService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for AlertDestinationService yet -- use the CLI or curl example below.","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../dataplanes/01H.../alert-destinations\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"persona":"Authenticated (API key or session token)","httpVerb":"GET","httpPath":"/v1/customers/{customer_id}/dataplanes/{workspace_id}/alert-destinations","slug":"list-alert-destinations"}Create an alert destination
Changed in v0.11.0 (behaviour changes): Creating, changing or deleting an alert destination from the Admin Console, the Developer Console or the API now writes one alert_destinations audit record naming the signed-in user, with success set to false when the change is refused after the sign-in and permission checks; no record holds a credential. Until the Admin Console stops writing its own record, a change made there writes two.
What it does: Stores the credential through the secret service and then inserts the destination row referencing it. Returns INVALID_ARGUMENT when the type is unspecified, when the secret is empty or (for a webhook) not the {url, signing_key} object, or when the resulting URL names a non-public host. Every destination type is accepted here, PagerDuty included. The dashboard's own create form offers only Slack and webhook, so a PagerDuty destination is created through this API rather than through that form.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | yes | undocumented |
workspace_id | yes | undocumented |
type | yes | Any member of the enum other than ALERT_DESTINATION_TYPE_UNSPECIFIED. |
secret | yes | The raw credential, write-only. Its shape depends on type: - ALERT_DESTINATION_TYPE_SLACK: the incoming-webhook URL itself. Opaque to us beyond being a public https URL. - ALERT_DESTINATION_TYPE_WEBHOOK: a JSON object {"url":"https://...","signing_key":"..."} -- the shape the notifier signs with. - ALERT_DESTINATION_TYPE_PAGERDUTY: an Events API v2 routing key, opaque to us beyond being non-empty. Surrounding whitespace is trimmed before anything else looks at it, so the value validated is byte-for-byte the value stored. It is written through the secret service and nowhere else: not onto the alert_destinations row, not into a log line, and not onto any response on this surface. Validation errors describe the expected shape and never echo any part of what was submitted. Slack and webhook both yield a URL the management plane will fetch, so it must name a PUBLIC host: loopback, private, link-local and cloud-metadata addresses are refused here, and re-checked against the address actually dialled at delivery time (alerting/dialguard.go). A PagerDuty routing key carries no such address and is not URL-checked. |
classes | no | Severity classes to route here. Empty is valid and creates a destination that routes nothing until updated. |
enabled | no | Defaults to true when absent. |
Response fields:
| Field | Required | Description |
|---|---|---|
destination | no | undocumented |
{"signatures":{"go":"c.AlertDestination().CreateAlertDestination(ctx, \u0026alertingv1.CreateAlertDestinationRequest{...})","python":"client.alertdestination.createalertdestination(...)","typescript":"client.alertdestination.createalertdestination({...})","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../dataplanes/01H.../alert-destinations\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"type\": \"...\",\n \"secret\": \"...\",\n \"classes\": [],\n \"enabled\": false\n }'"},"examples":{"go":"// No Go SDK wrapper for AlertDestinationService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for AlertDestinationService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for AlertDestinationService yet -- use the CLI or curl example below.","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../dataplanes/01H.../alert-destinations\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"type\": \"...\",\n \"secret\": \"...\",\n \"classes\": [],\n \"enabled\": false\n }'"},"persona":"Authenticated (API key or session token)","httpVerb":"POST","httpPath":"/v1/customers/{customer_id}/dataplanes/{workspace_id}/alert-destinations","slug":"create-an-alert-destination"}Update an alert destination
Changed in v0.11.0 (behaviour changes): Creating, changing or deleting an alert destination from the Admin Console, the Developer Console or the API now writes one alert_destinations audit record naming the signed-in user, with success set to false when the change is refused after the sign-in and permission checks; no record holds a credential. Until the Admin Console stops writing its own record, a change made there writes two.
What it does: Applies a partial update to the two mutable fields, classes and enabled. The type and the credential are set once at creation and are not reachable from here.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | yes | undocumented |
workspace_id | yes | undocumented |
id | yes | undocumented |
classes | no | Present replaces the stored classes wholesale; absent leaves them alone. |
enabled | no | Present sets enabled; absent leaves it alone. |
Response fields:
| Field | Required | Description |
|---|---|---|
destination | no | undocumented |
{"signatures":{"go":"c.AlertDestination().UpdateAlertDestination(ctx, \u0026alertingv1.UpdateAlertDestinationRequest{...})","python":"client.alertdestination.updatealertdestination(...)","typescript":"client.alertdestination.updatealertdestination({...})","curl":"curl -X PATCH \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../dataplanes/01H.../alert-destinations/01H...\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"classes\": {},\n \"enabled\": false\n }'"},"examples":{"go":"// No Go SDK wrapper for AlertDestinationService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for AlertDestinationService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for AlertDestinationService yet -- use the CLI or curl example below.","curl":"curl -X PATCH \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../dataplanes/01H.../alert-destinations/01H...\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"classes\": {},\n \"enabled\": false\n }'"},"persona":"Authenticated (API key or session token)","httpVerb":"PATCH","httpPath":"/v1/customers/{customer_id}/dataplanes/{workspace_id}/alert-destinations/{id}","slug":"update-an-alert-destination"}Delete an alert destination
Changed in v0.11.0 (behaviour changes): Creating, changing or deleting an alert destination from the Admin Console, the Developer Console or the API now writes one alert_destinations audit record naming the signed-in user, with success set to false when the change is refused after the sign-in and permission checks; no record holds a credential. Until the Admin Console stops writing its own record, a change made there writes two.
What it does: Removes the destination and then purges its credential. Returns NOT_FOUND when no such destination exists in this workspace.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | yes | undocumented |
workspace_id | yes | undocumented |
id | yes | undocumented |
{"signatures":{"go":"c.AlertDestination().DeleteAlertDestination(ctx, \u0026alertingv1.DeleteAlertDestinationRequest{...})","python":"client.alertdestination.deletealertdestination(...)","typescript":"client.alertdestination.deletealertdestination({...})","curl":"curl -X DELETE \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../dataplanes/01H.../alert-destinations/01H...\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"examples":{"go":"// No Go SDK wrapper for AlertDestinationService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for AlertDestinationService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for AlertDestinationService yet -- use the CLI or curl example below.","curl":"curl -X DELETE \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../dataplanes/01H.../alert-destinations/01H...\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"persona":"Authenticated (API key or session token)","httpVerb":"DELETE","httpPath":"/v1/customers/{customer_id}/dataplanes/{workspace_id}/alert-destinations/{id}","slug":"delete-an-alert-destination"}Send a test alert
What it does: Appends one synthetic, already-closed alert event for the workspace, which the dispatcher then fans out to every enabled destination whose classes include "notify". It exercises the workspace's whole delivery pipeline rather than one destination: alert_events carries no destination_id by design, because alert_deliveries is the per-destination fan-out. Gated on alert_destinations.EDIT rather than an atom of its own. It writes no destination state, but it makes every destination in the workspace emit a real delivery, so the right bar is "may change this workspace's alert routing" -- which .edit already means. There is deliberately no fifth atom.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | yes | undocumented |
workspace_id | yes | undocumented |
Response fields:
| Field | Required | Description |
|---|---|---|
event_id | output-only | The synthetic alert_events row this call appended. |
{"signatures":{"go":"c.AlertDestination().TestSendAlert(ctx, \u0026alertingv1.TestSendAlertRequest{...})","python":"client.alertdestination.testsendalert(...)","typescript":"client.alertdestination.testsendalert({...})","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../dataplanes/01H.../alert-destinations/test-send\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'"},"examples":{"go":"// No Go SDK wrapper for AlertDestinationService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for AlertDestinationService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for AlertDestinationService yet -- use the CLI or curl example below.","curl":"curl -X POST \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../dataplanes/01H.../alert-destinations/test-send\" \\\n -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'"},"persona":"Authenticated (API key or session token)","httpVerb":"POST","httpPath":"/v1/customers/{customer_id}/dataplanes/{workspace_id}/alert-destinations/test-send","slug":"send-a-test-alert"}