Policies

A routing policy maps each incoming alert severity (critical, high, medium, low) to an outcome — whether it opens an incident, sends a provisional page, posts a notification, or is dropped — and, for paging outcomes, which escalation policy handles it. Every organization has a seeded default routing policy that reproduces the platform’s built-in severity rules; you can create additional named policies and point inbound integrations at them.

A complete routing policy always carries exactly one rule per severity — four rules in total. Create and update requests that supply rules must include all four.

`GET /routing/policies`

List all routing policies for your organization. Returns policy metadata only — rules are not included in list responses.

Response fields

data

object[]

required

Array of routing policy objects.

Show Policy object fields

string

required

Unique policy ID (UUID).

orgId

string

required

The organization this policy belongs to.

name

string

required

Display name of the policy. Unique within your organization.

description

string | null

required

Optional description. null if not set.

isDefault

boolean

required

true for the org-wide fallback policy, which cannot be deleted.

createdAt

string

required

ISO 8601 creation timestamp.

updatedAt

string

required

ISO 8601 last-updated timestamp.

curl --request GET \
  --url https://api.scaling.cloud/v1/routing/policies \
  --header 'Authorization: Bearer scl_live_your_api_key_here'

{
  "data": [
    {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "orgId": "org_2abc123def456",
      "name": "Default routing",
      "description": "Default severity routing for all alerts",
      "isDefault": true,
      "createdAt": "2026-01-05T08:00:00.000Z",
      "updatedAt": "2026-03-20T16:45:00.000Z"
    },
    {
      "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
      "orgId": "org_2abc123def456",
      "name": "Payments routing",
      "description": null,
      "isDefault": false,
      "createdAt": "2026-02-14T09:00:00.000Z",
      "updatedAt": "2026-02-14T09:00:00.000Z"
    }
  ]
}

{
  "statusCode": 401,
  "type": "not_authorized_error",
  "code": "not_authorized",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Error codes

HTTP	Code	Description
`401`	`not_authorized`	Missing or invalid API key.
`500`	`server_error`	Unexpected server error.

`POST /routing/policies`

Create a new named routing policy. The name must be unique within your organization. Supply a complete four-rule set, or omit rules to seed the policy with the same sensible per-severity defaults as the org default.

Request body

name

string

required

Display name for the policy. Must be unique within your organization. 1–255 characters.

description

string | null

Optional description of the policy’s purpose.

rules

object[]

Optional. When supplied, must contain exactly four rules — one per severity. When omitted, the policy is seeded with the platform defaults.

Show Rule fields

severity

string

required

One of critical, high, medium, low. Each severity must appear exactly once.

outcome

string

required

One of incident, provisional_page, notification, drop.

escalationPolicyId

string | null

required

For paging outcomes, the escalation policy to page. Must reference an escalation policy in your organization, or null to fall back to the alert’s component default.

Response fields

data

object

required

The created routing policy, including its rules.

curl --request POST \
  --url https://api.scaling.cloud/v1/routing/policies \
  --header 'Authorization: Bearer scl_live_your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Payments routing",
    "description": "Stricter routing for payment incidents",
    "rules": [
      { "severity": "critical", "outcome": "incident", "escalationPolicyId": "f6a7b8c9-d0e1-2345-fabc-456789012345" },
      { "severity": "high", "outcome": "provisional_page", "escalationPolicyId": null },
      { "severity": "medium", "outcome": "notification", "escalationPolicyId": null },
      { "severity": "low", "outcome": "notification", "escalationPolicyId": null }
    ]
  }'

{
  "data": {
    "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "orgId": "org_2abc123def456",
    "name": "Payments routing",
    "description": "Stricter routing for payment incidents",
    "isDefault": false,
    "createdAt": "2026-04-07T10:00:00.000Z",
    "updatedAt": "2026-04-07T10:00:00.000Z",
    "rules": [
      { "severity": "critical", "outcome": "incident", "escalationPolicyId": "f6a7b8c9-d0e1-2345-fabc-456789012345" },
      { "severity": "high", "outcome": "provisional_page", "escalationPolicyId": null },
      { "severity": "medium", "outcome": "notification", "escalationPolicyId": null },
      { "severity": "low", "outcome": "notification", "escalationPolicyId": null }
    ]
  }
}

{
  "statusCode": 409,
  "type": "invalid_request_error",
  "code": "name_conflict",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "statusCode": 400,
  "type": "invalid_request_error",
  "code": "invalid_request",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Error codes

HTTP	Code	Description
`400`	`invalid_request`	The rule set is incomplete, carries an invalid outcome, or references an escalation policy that does not exist in your organization.
`401`	`not_authorized`	Missing or invalid API key.
`409`	`name_conflict`	Your organization already has a policy with this name.
`500`	`server_error`	Unexpected server error.

`GET /routing/policies/{policyId}`

Retrieve a single routing policy by ID, including its four severity rules.

Path parameters

policyId

string

required

The UUID of the policy to retrieve.

Response fields

data

object

required

The policy with its rules.

Show Policy object fields

string

required

Unique policy ID (UUID).

orgId

string

required

The organization this policy belongs to.

name

string

required

Display name of the policy.

description

string | null

required

Description, or null if not set.

isDefault

boolean

required

true for the org-wide fallback policy.

createdAt

string

required

ISO 8601 creation timestamp.

updatedAt

string

required

ISO 8601 last-updated timestamp.

rules

object[]

required

The four severity rules. Each rule has severity, outcome, and a nullable escalationPolicyId.

curl --request GET \
  --url https://api.scaling.cloud/v1/routing/policies/e5f6a7b8-c9d0-1234-efab-345678901234 \
  --header 'Authorization: Bearer scl_live_your_api_key_here'

{
  "data": {
    "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "orgId": "org_2abc123def456",
    "name": "Payments routing",
    "description": "Stricter routing for payment incidents",
    "isDefault": false,
    "createdAt": "2026-02-14T09:00:00.000Z",
    "updatedAt": "2026-02-14T09:00:00.000Z",
    "rules": [
      { "severity": "critical", "outcome": "incident", "escalationPolicyId": "f6a7b8c9-d0e1-2345-fabc-456789012345" },
      { "severity": "high", "outcome": "provisional_page", "escalationPolicyId": null },
      { "severity": "medium", "outcome": "notification", "escalationPolicyId": null },
      { "severity": "low", "outcome": "notification", "escalationPolicyId": null }
    ]
  }
}

{
  "statusCode": 404,
  "type": "invalid_request_error",
  "code": "not_found",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Error codes

HTTP	Code	Description
`401`	`not_authorized`	Missing or invalid API key.
`404`	`not_found`	No policy found with the given ID in your organization.
`500`	`server_error`	Unexpected server error.

`PUT /routing/policies/{policyId}`

Replace a routing policy in full — its name, description, and all four severity rules are overwritten atomically. The request body must contain a complete four-rule set.

Path parameters

policyId

string

required

The UUID of the policy to update.

Request body

name

string

required

Display name for the policy. Must be unique within your organization. 1–255 characters.

description

string | null

required

Description. Pass null to clear it.

rules

object[]

required

Exactly four rules — one per severity. Each rule has severity, outcome, and a nullable escalationPolicyId.

Response fields

data

object

required

The updated policy, including its rules.

curl --request PUT \
  --url https://api.scaling.cloud/v1/routing/policies/e5f6a7b8-c9d0-1234-efab-345678901234 \
  --header 'Authorization: Bearer scl_live_your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Payments routing",
    "description": "Updated routing for payment incidents",
    "rules": [
      { "severity": "critical", "outcome": "incident", "escalationPolicyId": null },
      { "severity": "high", "outcome": "incident", "escalationPolicyId": null },
      { "severity": "medium", "outcome": "notification", "escalationPolicyId": null },
      { "severity": "low", "outcome": "drop", "escalationPolicyId": null }
    ]
  }'

{
  "data": {
    "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "orgId": "org_2abc123def456",
    "name": "Payments routing",
    "description": "Updated routing for payment incidents",
    "isDefault": false,
    "createdAt": "2026-02-14T09:00:00.000Z",
    "updatedAt": "2026-04-07T11:00:00.000Z",
    "rules": [
      { "severity": "critical", "outcome": "incident", "escalationPolicyId": null },
      { "severity": "high", "outcome": "incident", "escalationPolicyId": null },
      { "severity": "medium", "outcome": "notification", "escalationPolicyId": null },
      { "severity": "low", "outcome": "drop", "escalationPolicyId": null }
    ]
  }
}

{
  "statusCode": 404,
  "type": "invalid_request_error",
  "code": "not_found",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Error codes

HTTP	Code	Description
`400`	`invalid_request`	The rule set is incomplete, carries an invalid outcome, or references an escalation policy that does not exist in your organization.
`401`	`not_authorized`	Missing or invalid API key.
`404`	`not_found`	No policy found with the given ID in your organization.
`409`	`name_conflict`	Your organization already has a policy with this name.
`500`	`server_error`	Unexpected server error.

`DELETE /routing/policies/{policyId}`

Delete a routing policy. Inbound integrations that referenced the policy revert to the org default. This action is permanent.

The seeded default routing policy is the org-wide fallback and cannot be deleted. A delete targeting it fails with a 409 default_undeletable error.

Path parameters

policyId

string

required

The UUID of the policy to delete.

curl --request DELETE \
  --url https://api.scaling.cloud/v1/routing/policies/e5f6a7b8-c9d0-1234-efab-345678901234 \
  --header 'Authorization: Bearer scl_live_your_api_key_here'

(No content)

{
  "statusCode": 409,
  "type": "invalid_request_error",
  "code": "default_undeletable",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "statusCode": 404,
  "type": "invalid_request_error",
  "code": "not_found",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Error codes

HTTP	Code	Description
`401`	`not_authorized`	Missing or invalid API key.
`404`	`not_found`	No policy found with the given ID in your organization.
`409`	`default_undeletable`	The policy is your organization’s default and cannot be deleted.
`500`	`server_error`	Unexpected server error.

Overview

Incidents

On-call Schedules

Escalation Policies

Routing Policies

Working Hours

Team

`GET /routing/policies`

Response fields

Error codes

`POST /routing/policies`

Request body

Response fields

Error codes

`GET /routing/policies/{policyId}`

Path parameters

Response fields

Error codes

`PUT /routing/policies/{policyId}`

Path parameters

Request body

Response fields

Error codes

`DELETE /routing/policies/{policyId}`

Path parameters

Error codes

​GET /routing/policies

​Response fields

​Error codes

​POST /routing/policies

​Request body

​Response fields

​Error codes

​GET /routing/policies/{policyId}

​Path parameters

​Response fields

​Error codes

​PUT /routing/policies/{policyId}

​Path parameters

​Request body

​Response fields

​Error codes

​DELETE /routing/policies/{policyId}

​Path parameters

​Error codes

`GET /routing/policies`

Response fields

Error codes

`POST /routing/policies`

Request body

Response fields

Error codes

`GET /routing/policies/{policyId}`

Path parameters

Response fields

Error codes

`PUT /routing/policies/{policyId}`

Path parameters

Request body

Response fields

Error codes

`DELETE /routing/policies/{policyId}`

Path parameters

Error codes