---
title: "Replace a team's escalation policy"
method: PUT
path: "/api/{org_id}/oncall/teams/{team_id}/policy"
tags: ["OnCall"]
---

# Replace a team's escalation policy

`PUT /api/{org_id}/oncall/teams/{team_id}/policy`

## Request

- Base URL: `https://api.openobserve.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.openobserve.ai/api/{org_id}/oncall/teams/{team_id}/policy`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/openobserve/apis/openobserve-api-http/docs/api/:org_id/oncall/teams/:team_id/policy/put.ts> (a function with typed inputs; its response is checked against the schema)

## Path parameters

- `org_id` string, required
- `team_id` string, required

## Request body

- SetPolicyRequest: `rungs` is a full replace; the two optional fields are left as they were when absent.
  - `destinations` string[], nullable: Alert Destination names to page through. Absent leaves them unchanged.
  - `l0` L0Policy: A team's L0 block. Ships with every auto-created policy, so nobody has to configure L0 to benefit from it. No `allow_demotion` knob: the ratchet is an invariant of the engine, not a team preference.
    - `allow_downgrade` boolean, required: A `Downgrade` needs `medium` or `high` confidence to ride quieter channels.
    - `allow_promotion` boolean, required
    - `allow_suppress` boolean, required: Opt-in; when enabled only a `high`-confidence Suppress silences the page.
    - `max_promotion_steps` integer, required: How far one verdict may raise a severity, so a P4 cannot become a P1 in a single hop.
    - `mode` L0Modes, required: Per-severity modes, exactly as the `l0_json` column spells them.
      - `P1` 'parallel' | 'gate' | 'only' | 'off', required: How L0 relates to paging at one severity.
      - `P2` 'parallel' | 'gate' | 'only' | 'off', required: How L0 relates to paging at one severity.
      - `P3` 'parallel' | 'gate' | 'only' | 'off', required: How L0 relates to paging at one severity.
      - `P4` 'parallel' | 'gate' | 'only' | 'off', required: How L0 relates to paging at one severity.
    - `triage_budget_seconds` integer, required
  - `rungs` PriorityRung[], required
    - `channels` Channel[], required: Applies to everyone paged at this priority — the primary and the secondary are not treated differently.
    - `priority` integer, required
    - `steps` LadderStep[], required: Empty means this priority never pages a human.
      - `after_micros` integer, required: Delay from `opened_at`, in microseconds. Unique within a rung.
      - `targets` EscalationTarget[], required: Paged simultaneously. At least one.
        - union: One thing a level pages. A level may hold several, and they fire together. Firing together is the only mechanism for paging more than one person. No stacking, no overlap, no derivation — which keeps "who does this level wake" answerable by reading it.
          - object: A named rotation, by id rather than by name: a rotation is renameable, and a stored policy must not start paging a different position because somebody fixed a typo on a calendar.
            - `kind` 'rotation', required
            - `mode` 'on_call' | 'all': How much of a rotation a level pages. Mirrors incident.io's `schedule_mode`, and is why three kinds are enough: "everyone in this rotation" is a mode, not a fourth kind.
            - `rotation_id` string, required
          - object: One named person, by email; a ladder step skips them while away, a handoff does not.
            - `email` string, required
            - `kind` 'user', required
          - object: Every member of the team — the last resort at the bottom of a ladder. Blind to rotations, and skips the away only while someone else is left: it is where a page falls back when every rotation has failed to produce anybody, and a last resort that filters itself down to nobody is not one.
            - `kind` 'whole_team', required
  - `template` string, nullable: Template override for on-call messages; absent leaves it, null or "" clears it.

## Response `200`

Success

- EscalationPolicy: A team's escalation policy.
  - `destinations` string[]: Alert Destination names this team pages through when a rung includes the Webhook channel. Reuses the destinations an org already has rather than storing URLs twice.
  - `id` string, required
  - `l0` L0Policy: A team's L0 block. Ships with every auto-created policy, so nobody has to configure L0 to benefit from it. No `allow_demotion` knob: the ratchet is an invariant of the engine, not a team preference.
    - `allow_downgrade` boolean, required: A `Downgrade` needs `medium` or `high` confidence to ride quieter channels.
    - `allow_promotion` boolean, required
    - `allow_suppress` boolean, required: Opt-in; when enabled only a `high`-confidence Suppress silences the page.
    - `max_promotion_steps` integer, required: How far one verdict may raise a severity, so a P4 cannot become a P1 in a single hop.
    - `mode` L0Modes, required: Per-severity modes, exactly as the `l0_json` column spells them.
      - `P1` 'parallel' | 'gate' | 'only' | 'off', required: How L0 relates to paging at one severity.
      - `P2` 'parallel' | 'gate' | 'only' | 'off', required: How L0 relates to paging at one severity.
      - `P3` 'parallel' | 'gate' | 'only' | 'off', required: How L0 relates to paging at one severity.
      - `P4` 'parallel' | 'gate' | 'only' | 'off', required: How L0 relates to paging at one severity.
    - `triage_budget_seconds` integer, required
  - `org_id` string, required
  - `rungs` PriorityRung[], required
    - `channels` Channel[], required: Applies to everyone paged at this priority — the primary and the secondary are not treated differently.
    - `priority` integer, required
    - `steps` LadderStep[], required: Empty means this priority never pages a human.
      - `after_micros` integer, required: Delay from `opened_at`, in microseconds. Unique within a rung.
      - `targets` EscalationTarget[], required: Paged simultaneously. At least one.
        - union: One thing a level pages. A level may hold several, and they fire together. Firing together is the only mechanism for paging more than one person. No stacking, no overlap, no derivation — which keeps "who does this level wake" answerable by reading it.
          - object: A named rotation, by id rather than by name: a rotation is renameable, and a stored policy must not start paging a different position because somebody fixed a typo on a calendar.
            - `kind` 'rotation', required
            - `mode` 'on_call' | 'all': How much of a rotation a level pages. Mirrors incident.io's `schedule_mode`, and is why three kinds are enough: "everyone in this rotation" is a mode, not a fourth kind.
            - `rotation_id` string, required
          - object: One named person, by email; a ladder step skips them while away, a handoff does not.
            - `email` string, required
            - `kind` 'user', required
          - object: Every member of the team — the last resort at the bottom of a ladder. Blind to rotations, and skips the away only while someone else is left: it is where a page falls back when every rotation has failed to produce anybody, and a last resort that filters itself down to nobody is not one.
            - `kind` 'whole_team', required
  - `team_id` string, required
  - `template` string, nullable: Template override for this team's on-call messages; `None` uses each destination's.

---

[API](https://skmtc.dev/openobserve/apis/openobserve-api-http.md) - [All operations](https://skmtc.dev/openobserve/apis/openobserve-api-http/llms.txt) - [OpenAPI document](https://skmtc.dev/openobserve/apis/openobserve-api-http/revisions/0529b8a10252?raw)