> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scaling.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Policies

> Create and manage escalation policies for your organization.

An escalation policy defines an ordered sequence of layers, each targeting an on-call schedule or a set of users. When an incident is triggered, scaling.cloud notifies the first layer. If that layer does not acknowledge within `ackTimeoutMinutes`, it escalates to the next layer.

<Note>
  Policy layers are managed separately. See [Policy Layers](/api/escalation/layers) for endpoints that add, update, reorder, or remove layers from a policy.
</Note>

***

## `GET /escalation/policies`

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

### Response fields

<ResponseField name="data" type="object[]" required>
  Array of escalation policy objects.

  <Expandable title="Policy object fields">
    <ResponseField name="id" type="string" required>
      Unique policy ID (UUID).
    </ResponseField>

    <ResponseField name="orgId" type="string" required>
      The organization this policy belongs to.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Display name of the policy. Unique within your organization.
    </ResponseField>

    <ResponseField name="description" type="string | null" required>
      Optional description. `null` if not set.
    </ResponseField>

    <ResponseField name="createdBy" type="string" required>
      ID of the user or API key that created the policy.
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      ISO 8601 creation timestamp.
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      ISO 8601 last-updated timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.scaling.cloud/v1/escalation/policies \
    --header 'Authorization: Bearer scl_live_your_api_key_here'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
        "orgId": "org_2abc123def456",
        "name": "Platform default",
        "description": "Default escalation for all platform incidents",
        "createdBy": "user_9xyz",
        "createdAt": "2026-01-05T08:00:00.000Z",
        "updatedAt": "2026-03-20T16:45:00.000Z"
      },
      {
        "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
        "orgId": "org_2abc123def456",
        "name": "Data pipeline critical",
        "description": null,
        "createdBy": "user_8wxy",
        "createdAt": "2026-02-14T09:00:00.000Z",
        "updatedAt": "2026-02-14T09:00:00.000Z"
      }
    ]
  }
  ```

  ```json 401 theme={null}
  {
    "statusCode": 401,
    "type": "not_authorized_error",
    "code": "not_authorized",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</ResponseExample>

### Error codes

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

***

## `POST /escalation/policies`

Create a new escalation policy. The `name` must be unique within your organization. Add layers separately after creation using `POST /escalation/policies/{policyId}/layers`.

### Request body

<ParamField body="name" type="string" required>
  Display name for the policy. Must be unique within your organization. 1–255 characters.
</ParamField>

<ParamField body="description" type="string">
  Optional description of the policy's purpose.
</ParamField>

### Response fields

<ResponseField name="data" type="object" required>
  The created escalation policy.

  <Expandable title="Policy object fields">
    <ResponseField name="id" type="string" required>
      Unique policy ID (UUID). Stable — never changes after creation.
    </ResponseField>

    <ResponseField name="orgId" type="string" required>
      The organization this policy belongs to.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Display name of the policy.
    </ResponseField>

    <ResponseField name="description" type="string | null" required>
      Description, or `null` if not provided.
    </ResponseField>

    <ResponseField name="createdBy" type="string" required>
      ID of the user or API key that created the policy.
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      ISO 8601 creation timestamp.
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      ISO 8601 last-updated timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.scaling.cloud/v1/escalation/policies \
    --header 'Authorization: Bearer scl_live_your_api_key_here' \
    --header 'Content-Type: application/json' \
    --data '{
      "name": "Platform default",
      "description": "Default escalation for all platform incidents"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "orgId": "org_2abc123def456",
      "name": "Platform default",
      "description": "Default escalation for all platform incidents",
      "createdBy": "user_9xyz",
      "createdAt": "2026-04-07T10:00:00.000Z",
      "updatedAt": "2026-04-07T10:00:00.000Z"
    }
  }
  ```

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

  ```json 500 theme={null}
  {
    "statusCode": 500,
    "type": "invalid_error",
    "code": "server_error",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</ResponseExample>

### Error codes

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

***

## `GET /escalation/policies/{policyId}`

Retrieve a single escalation policy by ID, including all of its layers ordered by `position`.

### Path parameters

<ParamField path="policyId" type="string" required>
  The UUID of the policy to retrieve.
</ParamField>

### Response fields

<ResponseField name="data" type="object" required>
  The policy with its layers.

  <Expandable title="Policy object fields">
    <ResponseField name="id" type="string" required>
      Unique policy ID (UUID).
    </ResponseField>

    <ResponseField name="orgId" type="string" required>
      The organization this policy belongs to.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Display name of the policy.
    </ResponseField>

    <ResponseField name="description" type="string | null" required>
      Description, or `null` if not set.
    </ResponseField>

    <ResponseField name="createdBy" type="string" required>
      ID of the user or API key that created the policy.
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      ISO 8601 creation timestamp.
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      ISO 8601 last-updated timestamp.
    </ResponseField>

    <ResponseField name="layers" type="object[]" required>
      Ordered escalation layers. See [Policy Layers](/api/escalation/layers) for field definitions.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.scaling.cloud/v1/escalation/policies/d4e5f6a7-b8c9-0123-defa-234567890123 \
    --header 'Authorization: Bearer scl_live_your_api_key_here'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "orgId": "org_2abc123def456",
      "name": "Platform default",
      "description": "Default escalation for all platform incidents",
      "createdBy": "user_9xyz",
      "createdAt": "2026-01-05T08:00:00.000Z",
      "updatedAt": "2026-03-20T16:45:00.000Z",
      "layers": [
        {
          "id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
          "policyId": "d4e5f6a7-b8c9-0123-defa-234567890123",
          "orgId": "org_2abc123def456",
          "position": 1,
          "ackTimeoutMinutes": 5,
          "target": {
            "type": "schedule",
            "scheduleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "createdAt": "2026-01-05T08:10:00.000Z",
          "updatedAt": "2026-01-05T08:10:00.000Z"
        },
        {
          "id": "a7b8c9d0-e1f2-3456-abcd-567890123456",
          "policyId": "d4e5f6a7-b8c9-0123-defa-234567890123",
          "orgId": "org_2abc123def456",
          "position": 2,
          "ackTimeoutMinutes": 10,
          "target": {
            "type": "users",
            "userIds": ["user_mgr001", "user_mgr002"]
          },
          "createdAt": "2026-01-05T08:12:00.000Z",
          "updatedAt": "2026-01-05T08:12:00.000Z"
        }
      ]
    }
  }
  ```

  ```json 404 theme={null}
  {
    "statusCode": 404,
    "type": "invalid_request_error",
    "code": "not_found",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</ResponseExample>

### 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.                                |

***

## `PATCH /escalation/policies/{policyId}`

Update one or more fields on an escalation policy. All fields are optional — only the fields you include are updated. To update layers, use the layer endpoints.

### Path parameters

<ParamField path="policyId" type="string" required>
  The UUID of the policy to update.
</ParamField>

### Request body

<ParamField body="name" type="string">
  New display name for the policy. Must be unique within your organization. 1–255 characters.
</ParamField>

<ParamField body="description" type="string | null">
  Updated description. Pass `null` to clear the description.
</ParamField>

### Response fields

<ResponseField name="data" type="object" required>
  The updated policy object (metadata only — does not include layers).
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url https://api.scaling.cloud/v1/escalation/policies/d4e5f6a7-b8c9-0123-defa-234567890123 \
    --header 'Authorization: Bearer scl_live_your_api_key_here' \
    --header 'Content-Type: application/json' \
    --data '{
      "description": "Default escalation — platform, infrastructure, and data teams"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "orgId": "org_2abc123def456",
      "name": "Platform default",
      "description": "Default escalation — platform, infrastructure, and data teams",
      "createdBy": "user_9xyz",
      "createdAt": "2026-01-05T08:00:00.000Z",
      "updatedAt": "2026-04-07T11:00:00.000Z"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "statusCode": 404,
    "type": "invalid_request_error",
    "code": "not_found",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</ResponseExample>

### 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.                                |

***

## `DELETE /escalation/policies/{policyId}`

Delete an escalation policy and all of its layers. This action is permanent.

<Warning>
  You cannot delete a policy that is currently attached to one or more active incidents. The request will fail with a `400 policy_in_use` error. Resolve or transfer all active incidents using this policy before deleting it.
</Warning>

### Path parameters

<ParamField path="policyId" type="string" required>
  The UUID of the policy to delete.
</ParamField>

### Response fields

<ResponseField name="success" type="boolean" required>
  `true` when the policy was deleted.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url https://api.scaling.cloud/v1/escalation/policies/d4e5f6a7-b8c9-0123-defa-234567890123 \
    --header 'Authorization: Bearer scl_live_your_api_key_here'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true
  }
  ```

  ```json 400 — policy in use theme={null}
  {
    "statusCode": 400,
    "type": "invalid_request_error",
    "code": "policy_in_use",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```

  ```json 404 theme={null}
  {
    "statusCode": 404,
    "type": "invalid_request_error",
    "code": "not_found",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</ResponseExample>

### Error codes

| HTTP  | Code             | Description                                                                   |
| ----- | ---------------- | ----------------------------------------------------------------------------- |
| `400` | `policy_in_use`  | The policy is attached to one or more active incidents and cannot be deleted. |
| `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.                                                      |