DocsAPI reference

Escalation paths

An escalation path decides who reviews a request once the pipeline hands it to a person, and what happens when nobody answers in time.

Updated Sep 21, 2026

To change a path, create a revision, then activate it. Activation affects requests that reach a person from then on. A request already waiting for review stays with the revision it was routed with, so its reviewers and timers do not change.

List escalation paths

GET/api/v1/escalation-pathsSession or API keyRequires escalation_path.read

Returns the organization's escalation paths, one entry per key, with the active revision number and a summary of the history. Live paths are returned unless status says otherwise; an archived path carries archived_at.

Request

Parameters

Parameter	Type	Description
`status`	query · enum	Which paths to return. `live` (the default) leaves archived paths out, `archived` returns only them, and `all` returns both. One of `live`, `archived`, `all`
`limit`	query · integer	How many paths to return. Defaults to 50.

Response

Response codes

Status	Body	Description
`200`	object	The paths
`400`	ErrorResponse	`status` is not live, archived, or all
`401`	ErrorResponse	You are not signed in
`403`	ErrorResponse	You cannot read escalation paths

Response body200

escalation_pathsarray<EscalationPathSummary>required

Example

GET /api/v1/escalation-paths

curl -X GET "$WITHHUMAN_URL/api/v1/escalation-paths" \
  -H "Authorization: Bearer $WITHHUMAN_API_KEY"

200 response

{
  "escalation_paths": [
    {
      "path_key": "string",
      "name": "string",
      "active_revision": 1,
      "latest_revision": 1,
      "revision_count": 1,
      "latest_created_at": "2026-09-08T12:02:11Z",
      "archived_at": "2026-09-08T12:02:11Z"
    }
  ]
}

Create an escalation path

POST/api/v1/escalation-pathsSession or API keyRequires escalation_path.write

Creates a path and its first revision in one call, from a complete document plus the key pipelines will reference. The document is validated first, including that every person and team it targets exists. The revision is created inactive, and it never changes. Activate it to put it into use.

A key can be used once. A key that belongs to a path, archived or not, is refused with 409 escalation_path_exists.

The response may carry warnings, for example a team whose members cannot decide requests. A warning never blocks creation.

Request

Request body

path_keystringrequired

namestringrequired

working_hoursarray<WorkingHoursSet>required

nodesarray<EscalationPathNode>required

repeatEscalationPathRepeat

Run the path again from the top when the nodes run out without a decision. Every condition is evaluated again on each run.

Response

Response codes

Status	Body	Description
`201`	EscalationPathRevisionSummary	The path's first revision, inactive
`400`	ErrorResponse	The document is invalid, a target does not exist, or the key is malformed
`401`	ErrorResponse	You are not signed in
`403`	ErrorResponse	You cannot edit escalation paths
`409`	ErrorResponse	The key is already in use

Response body201

iduuidrequired

path_keystringrequired

revisionint64required

The revision number. Revisions count up from 1.

is_activebooleanrequired

Whether requests are routed with this revision.

namestringrequired

The display name.

created_by_actor_iduuidrequired

The membership or organization-key actor that created the revision.

created_atdate-timerequired

archived_atdate-time

When the path was archived. Absent for a revision of a live path; an archived revision can no longer be activated.

working_hoursarray<WorkingHoursSet>required

The named working-hours sets the nodes refer to.

nodesarray<EscalationPathNode>required

The nodes, in order.

repeatEscalationPathRepeat

Run the path again from the top when the nodes run out without a decision. Every condition is evaluated again on each run.

document_versionintegerrequired

The version of the document format.

warningsarray<EscalationPathWarning>required

Advisory findings about the document's targets. They are computed when a revision is created or activated, and the list is empty on plain reads. A warning never blocks anything: a path narrows who decides, it never grants.

Example

POST /api/v1/escalation-paths

curl -X POST "$WITHHUMAN_URL/api/v1/escalation-paths" \
  -H "Authorization: Bearer $WITHHUMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "path_key": "string",
  "name": "string",
  "working_hours": [
    {
      "id": "uk-office",
      "name": "UK office hours",
      "timezone": "Europe/London",
      "intervals": [
        {
          "weekdays": [
            "mon"
          ],
          "start": "09:00",
          "end": "18:00"
        }
      ]
    }
  ],
  "nodes": [
    {
      "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "type": "level",
      "targets": [
        {
          "type": "user",
          "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71"
        }
      ],
      "escalate_after": "15m",
      "raise_urgency": true,
      "conditions": [
        {
          "type": "working_hours",
          "working_hours_id": "string",
          "active": true,
          "urgency": "standard",
          "when": {
            "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
            "field": "/request/arguments/amount_cents",
            "operator": "exists",
            "value": {}
          }
        }
      ],
      "then": [
        {}
      ],
      "else": [
        {}
      ],
      "working_hours_id": "string",
      "standard_only": true
    }
  ],
  "repeat": {
    "times": 1,
    "after": "1h"
  }
}'

201 response

{
  "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
  "path_key": "string",
  "revision": 1,
  "is_active": true,
  "name": "On-call engineers",
  "created_by_actor_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
  "created_at": "2026-09-08T12:02:11Z",
  "archived_at": "2026-09-08T12:02:11Z",
  "working_hours": [
    {
      "id": "uk-office",
      "name": "UK office hours",
      "timezone": "Europe/London",
      "intervals": [
        {
          "weekdays": [
            "mon"
          ],
          "start": "09:00",
          "end": "18:00"
        }
      ]
    }
  ],
  "nodes": [
    {
      "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "type": "level",
      "targets": [
        {
          "type": "user",
          "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71"
        }
      ],
      "escalate_after": "15m",
      "raise_urgency": true,
      "conditions": [
        {
          "type": "working_hours",
          "working_hours_id": "string",
          "active": true,
          "urgency": "standard",
          "when": {
            "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
            "field": "/request/arguments/amount_cents",
            "operator": "exists",
            "value": {}
          }
        }
      ],
      "then": [
        {}
      ],
      "else": [
        {}
      ],
      "working_hours_id": "string",
      "standard_only": true
    }
  ],
  "repeat": {
    "times": 1,
    "after": "1h"
  },
  "document_version": 1,
  "warnings": [
    {
      "code": "team_members_cannot_decide",
      "team_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "team_name": "string",
      "count": 1,
      "member_count": 1
    }
  ]
}

Retrieve an escalation path

GET/api/v1/escalation-paths/{path_key}Session or API keyRequires escalation_path.read

Returns the path's active revision with its full document. This is the revision new requests are routed with.

The ETag header carries the active revision number. Pass it as If-Match when you activate another revision.

Request

Parameters

Parameter	Type	Description
`path_key`required	path · string	The path's key. Lowercase letters, digits, dots, underscores and hyphens, up to 63 characters. You choose it when you create the first revision.

Response

Response codes

Status	Body	Description
`200`	EscalationPathRevisionSummary	The active revision
`401`	ErrorResponse	You are not signed in
`403`	ErrorResponse	You cannot read escalation paths
`404`	ErrorResponse	No such path, or no revision is active (an archived path never has one)

Response body200

iduuidrequired

path_keystringrequired

revisionint64required

The revision number. Revisions count up from 1.

is_activebooleanrequired

Whether requests are routed with this revision.

namestringrequired

The display name.

created_by_actor_iduuidrequired

The membership or organization-key actor that created the revision.

created_atdate-timerequired

archived_atdate-time

When the path was archived. Absent for a revision of a live path; an archived revision can no longer be activated.

working_hoursarray<WorkingHoursSet>required

The named working-hours sets the nodes refer to.

nodesarray<EscalationPathNode>required

The nodes, in order.

repeatEscalationPathRepeat

Run the path again from the top when the nodes run out without a decision. Every condition is evaluated again on each run.

document_versionintegerrequired

The version of the document format.

warningsarray<EscalationPathWarning>required

Example

GET /api/v1/escalation-paths/{path_key}

curl -X GET "$WITHHUMAN_URL/api/v1/escalation-paths/{path_key}" \
  -H "Authorization: Bearer $WITHHUMAN_API_KEY"

200 response

{
  "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
  "path_key": "string",
  "revision": 1,
  "is_active": true,
  "name": "On-call engineers",
  "created_by_actor_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
  "created_at": "2026-09-08T12:02:11Z",
  "archived_at": "2026-09-08T12:02:11Z",
  "working_hours": [
    {
      "id": "uk-office",
      "name": "UK office hours",
      "timezone": "Europe/London",
      "intervals": [
        {
          "weekdays": [
            "mon"
          ],
          "start": "09:00",
          "end": "18:00"
        }
      ]
    }
  ],
  "nodes": [
    {
      "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "type": "level",
      "targets": [
        {
          "type": "user",
          "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71"
        }
      ],
      "escalate_after": "15m",
      "raise_urgency": true,
      "conditions": [
        {
          "type": "working_hours",
          "working_hours_id": "string",
          "active": true,
          "urgency": "standard",
          "when": {
            "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
            "field": "/request/arguments/amount_cents",
            "operator": "exists",
            "value": {}
          }
        }
      ],
      "then": [
        {}
      ],
      "else": [
        {}
      ],
      "working_hours_id": "string",
      "standard_only": true
    }
  ],
  "repeat": {
    "times": 1,
    "after": "1h"
  },
  "document_version": 1,
  "warnings": [
    {
      "code": "team_members_cannot_decide",
      "team_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "team_name": "string",
      "count": 1,
      "member_count": 1
    }
  ]
}

Archive an escalation path

DELETE/api/v1/escalation-paths/{path_key}Session or API keyRequires escalation_path.activate

Archives the path and every revision it has. Nothing is deleted: the path is still listed with status=archived or all, its revisions can still be retrieved, and a request already routed with one of them keeps it. But the path is never active again, it takes no new revisions, and no pipeline can name it. Its key cannot be used for a new path.

A path that an active pipeline revision names, in a block or as the pipeline default, cannot be archived. The call fails with 409 escalation_path_in_use and lists those revisions in details.uses; replace them first.

Request

Parameters

Parameter	Type	Description
`path_key`required	path · string	The path's key. Lowercase letters, digits, dots, underscores and hyphens, up to 63 characters. You choose it when you create the first revision.

Response

Response codes

Status	Body	Description
`204`		The path is archived
`400`	ErrorResponse	`path_key` is malformed
`401`	ErrorResponse	You are not signed in
`403`	ErrorResponse	You cannot archive escalation paths
`404`	ErrorResponse	No such path
`409`	ErrorResponse	An active pipeline revision names the path (`escalation_path_in_use`), or the path is already archived (`escalation_path_archived`)

Example

DELETE /api/v1/escalation-paths/{path_key}

curl -X DELETE "$WITHHUMAN_URL/api/v1/escalation-paths/{path_key}" \
  -H "Authorization: Bearer $WITHHUMAN_API_KEY"

List escalation path revisions

GET/api/v1/escalation-paths/{path_key}/revisionsSession or API keyRequires escalation_path.read

Returns the path's revisions, newest first, without their documents. An archived path's revisions carry archived_at.

Paging is by cursor. When more revisions follow, the response carries next_cursor. Pass it back as cursor to get the next page. The last page has no next_cursor. total_count is how many revisions there are across every page.

Request

Parameters

Parameter	Type	Description
`path_key`required	path · string	The path's key. Lowercase letters, digits, dots, underscores and hyphens, up to 63 characters. You choose it when you create the first revision.
`cursor`	query · string	The `next_cursor` from the previous page.
`limit`	query · integer	How many revisions to return per page. Defaults to 50.

Response

Response codes

Status	Body	Description
`200`	object	The revisions, newest first
`400`	ErrorResponse	`cursor` is not a cursor this endpoint issued
`401`	ErrorResponse	You are not signed in
`403`	ErrorResponse	You cannot read escalation paths

Response body200

revisionsarray<EscalationPathRevisionSummary>required

The revisions on this page, newest first.

next_cursorstring

Present when another page follows.

total_countint64required

How many revisions the path has, across every page.

Example

GET /api/v1/escalation-paths/{path_key}/revisions

curl -X GET "$WITHHUMAN_URL/api/v1/escalation-paths/{path_key}/revisions" \
  -H "Authorization: Bearer $WITHHUMAN_API_KEY"

200 response

{
  "revisions": [
    {
      "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "path_key": "string",
      "revision": 1,
      "is_active": true,
      "name": "On-call engineers",
      "created_by_actor_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "created_at": "2026-09-08T12:02:11Z",
      "archived_at": "2026-09-08T12:02:11Z"
    }
  ],
  "next_cursor": "string",
  "total_count": 1
}

Create an escalation path revision

POST/api/v1/escalation-paths/{path_key}/revisionsSession or API keyRequires escalation_path.write

Creates a new revision of an existing path from a complete document. The document is validated first, including that every person and team it targets exists. The revision is created inactive, and it never changes. Activate it to put it into use.

The path must exist and not be archived. A new path is created with POST /api/v1/escalation-paths.

The response may carry warnings, for example a team whose members cannot decide requests. A warning never blocks creation.

Request

Parameters

Parameter	Type	Description
`path_key`required	path · string	The path's key. Lowercase letters, digits, dots, underscores and hyphens, up to 63 characters. You choose it when you create the first revision.

Request body

namestringrequired

A display name. Reviewers see it on the requests the path routes.

working_hoursarray<WorkingHoursSet>required

Named working-hours sets that if_else and defer nodes refer to by id. May be empty.

nodesarray<EscalationPathNode>required

The nodes, in order. At least one.

repeatEscalationPathRepeat

Run the path again from the top when the nodes run out without a decision. Every condition is evaluated again on each run.

Response

Response codes

Status	Body	Description
`201`	EscalationPathRevisionSummary	The new revision, inactive
`400`	ErrorResponse	The document is invalid, or a target does not exist
`401`	ErrorResponse	You are not signed in
`403`	ErrorResponse	You cannot edit escalation paths
`404`	ErrorResponse	No such path
`409`	ErrorResponse	The path is archived

Response body201

iduuidrequired

path_keystringrequired

revisionint64required

The revision number. Revisions count up from 1.

is_activebooleanrequired

Whether requests are routed with this revision.

namestringrequired

The display name.

created_by_actor_iduuidrequired

The membership or organization-key actor that created the revision.

created_atdate-timerequired

archived_atdate-time

When the path was archived. Absent for a revision of a live path; an archived revision can no longer be activated.

working_hoursarray<WorkingHoursSet>required

The named working-hours sets the nodes refer to.

nodesarray<EscalationPathNode>required

The nodes, in order.

repeatEscalationPathRepeat

Run the path again from the top when the nodes run out without a decision. Every condition is evaluated again on each run.

document_versionintegerrequired

The version of the document format.

warningsarray<EscalationPathWarning>required

Example

POST /api/v1/escalation-paths/{path_key}/revisions

curl -X POST "$WITHHUMAN_URL/api/v1/escalation-paths/{path_key}/revisions" \
  -H "Authorization: Bearer $WITHHUMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "On-call engineers",
  "working_hours": [
    {
      "id": "uk-office",
      "name": "UK office hours",
      "timezone": "Europe/London",
      "intervals": [
        {
          "weekdays": [
            "mon"
          ],
          "start": "09:00",
          "end": "18:00"
        }
      ]
    }
  ],
  "nodes": [
    {
      "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "type": "level",
      "targets": [
        {
          "type": "user",
          "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71"
        }
      ],
      "escalate_after": "15m",
      "raise_urgency": true,
      "conditions": [
        {
          "type": "working_hours",
          "working_hours_id": "string",
          "active": true,
          "urgency": "standard",
          "when": {
            "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
            "field": "/request/arguments/amount_cents",
            "operator": "exists",
            "value": {}
          }
        }
      ],
      "then": [
        {}
      ],
      "else": [
        {}
      ],
      "working_hours_id": "string",
      "standard_only": true
    }
  ],
  "repeat": {
    "times": 1,
    "after": "1h"
  }
}'

201 response

{
  "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
  "path_key": "string",
  "revision": 1,
  "is_active": true,
  "name": "On-call engineers",
  "created_by_actor_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
  "created_at": "2026-09-08T12:02:11Z",
  "archived_at": "2026-09-08T12:02:11Z",
  "working_hours": [
    {
      "id": "uk-office",
      "name": "UK office hours",
      "timezone": "Europe/London",
      "intervals": [
        {
          "weekdays": [
            "mon"
          ],
          "start": "09:00",
          "end": "18:00"
        }
      ]
    }
  ],
  "nodes": [
    {
      "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "type": "level",
      "targets": [
        {
          "type": "user",
          "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71"
        }
      ],
      "escalate_after": "15m",
      "raise_urgency": true,
      "conditions": [
        {
          "type": "working_hours",
          "working_hours_id": "string",
          "active": true,
          "urgency": "standard",
          "when": {
            "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
            "field": "/request/arguments/amount_cents",
            "operator": "exists",
            "value": {}
          }
        }
      ],
      "then": [
        {}
      ],
      "else": [
        {}
      ],
      "working_hours_id": "string",
      "standard_only": true
    }
  ],
  "repeat": {
    "times": 1,
    "after": "1h"
  },
  "document_version": 1,
  "warnings": [
    {
      "code": "team_members_cannot_decide",
      "team_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "team_name": "string",
      "count": 1,
      "member_count": 1
    }
  ]
}

Retrieve an escalation path revision

GET/api/v1/escalation-paths/{path_key}/revisions/{revision}Session or API keyRequires escalation_path.read

Returns one revision of a path, active or not, with its full document. Revisions of an archived path can still be retrieved.

Request

Parameters

Parameter	Type	Description
`path_key`required	path · string	The path's key. Lowercase letters, digits, dots, underscores and hyphens, up to 63 characters. You choose it when you create the first revision.
`revision`required	path · int64	The revision number. Revisions count up from 1.

Response

Response codes

Status	Body	Description
`200`	EscalationPathRevisionSummary	The revision
`400`	ErrorResponse	`revision` is not a positive integer
`401`	ErrorResponse	You are not signed in
`403`	ErrorResponse	You cannot read escalation paths
`404`	ErrorResponse	No such revision

Response body200

iduuidrequired

path_keystringrequired

revisionint64required

The revision number. Revisions count up from 1.

is_activebooleanrequired

Whether requests are routed with this revision.

namestringrequired

The display name.

created_by_actor_iduuidrequired

The membership or organization-key actor that created the revision.

created_atdate-timerequired

archived_atdate-time

When the path was archived. Absent for a revision of a live path; an archived revision can no longer be activated.

working_hoursarray<WorkingHoursSet>required

The named working-hours sets the nodes refer to.

nodesarray<EscalationPathNode>required

The nodes, in order.

repeatEscalationPathRepeat

Run the path again from the top when the nodes run out without a decision. Every condition is evaluated again on each run.

document_versionintegerrequired

The version of the document format.

warningsarray<EscalationPathWarning>required

Example

GET /api/v1/escalation-paths/{path_key}/revisions/{revision}

curl -X GET "$WITHHUMAN_URL/api/v1/escalation-paths/{path_key}/revisions/{revision}" \
  -H "Authorization: Bearer $WITHHUMAN_API_KEY"

200 response

{
  "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
  "path_key": "string",
  "revision": 1,
  "is_active": true,
  "name": "On-call engineers",
  "created_by_actor_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
  "created_at": "2026-09-08T12:02:11Z",
  "archived_at": "2026-09-08T12:02:11Z",
  "working_hours": [
    {
      "id": "uk-office",
      "name": "UK office hours",
      "timezone": "Europe/London",
      "intervals": [
        {
          "weekdays": [
            "mon"
          ],
          "start": "09:00",
          "end": "18:00"
        }
      ]
    }
  ],
  "nodes": [
    {
      "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "type": "level",
      "targets": [
        {
          "type": "user",
          "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71"
        }
      ],
      "escalate_after": "15m",
      "raise_urgency": true,
      "conditions": [
        {
          "type": "working_hours",
          "working_hours_id": "string",
          "active": true,
          "urgency": "standard",
          "when": {
            "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
            "field": "/request/arguments/amount_cents",
            "operator": "exists",
            "value": {}
          }
        }
      ],
      "then": [
        {}
      ],
      "else": [
        {}
      ],
      "working_hours_id": "string",
      "standard_only": true
    }
  ],
  "repeat": {
    "times": 1,
    "after": "1h"
  },
  "document_version": 1,
  "warnings": [
    {
      "code": "team_members_cannot_decide",
      "team_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "team_name": "string",
      "count": 1,
      "member_count": 1
    }
  ]
}

Activate an escalation path revision

POST/api/v1/escalation-paths/{path_key}/revisions/{revision}/activateSession or API keyRequires escalation_path.activate

Makes a revision the active one. Requests that reach a person from then on are routed with it. A request already waiting for review stays with the revision it was routed with, so its reviewers and timers do not change. Activating an older revision is how you roll back.

Pass the revision you expect to be active in If-Match, quoted, as returned in ETag. Pass "0" if no revision is active. If the active revision changed in the meantime, the call fails with 412 and nothing changes.

A revision of an archived path cannot be activated; the call fails with 409 escalation_path_archived.

Request

Parameters

Parameter	Type	Description
`path_key`required	path · string	The path's key. Lowercase letters, digits, dots, underscores and hyphens, up to 63 characters. You choose it when you create the first revision.
`revision`required	path · int64	The revision number. Revisions count up from 1.
`If-Match`required	header · string	The revision you expect to be active, quoted, for example `"2"`. Take it from the `ETag` of your last read. If the active revision changed in the meantime, the call fails with 412 and nothing changes. Escalation paths and webhook endpoints accept `"0"` when no revision is active. Pipelines always have an active revision.

Response

Response codes

Status	Body	Description
`200`	EscalationPathRevisionSummary	The revision, now active
`400`	ErrorResponse	`revision` or `If-Match` is malformed
`401`	ErrorResponse	You are not signed in
`403`	ErrorResponse	You cannot activate escalation paths
`404`	ErrorResponse	No such revision
`409`	ErrorResponse	The path is archived
`412`	ErrorResponse	`If-Match` does not match the active revision
`428`	ErrorResponse	The `If-Match` header is missing

Response body200

iduuidrequired

path_keystringrequired

revisionint64required

The revision number. Revisions count up from 1.

is_activebooleanrequired

Whether requests are routed with this revision.

namestringrequired

The display name.

created_by_actor_iduuidrequired

The membership or organization-key actor that created the revision.

created_atdate-timerequired

archived_atdate-time

When the path was archived. Absent for a revision of a live path; an archived revision can no longer be activated.

working_hoursarray<WorkingHoursSet>required

The named working-hours sets the nodes refer to.

nodesarray<EscalationPathNode>required

The nodes, in order.

repeatEscalationPathRepeat

Run the path again from the top when the nodes run out without a decision. Every condition is evaluated again on each run.

document_versionintegerrequired

The version of the document format.

warningsarray<EscalationPathWarning>required

Example

POST /api/v1/escalation-paths/{path_key}/revisions/{revision}/activate

curl -X POST "$WITHHUMAN_URL/api/v1/escalation-paths/{path_key}/revisions/{revision}/activate" \
  -H "Authorization: Bearer $WITHHUMAN_API_KEY" \
  -H "If-Match: "2""

200 response

{
  "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
  "path_key": "string",
  "revision": 1,
  "is_active": true,
  "name": "On-call engineers",
  "created_by_actor_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
  "created_at": "2026-09-08T12:02:11Z",
  "archived_at": "2026-09-08T12:02:11Z",
  "working_hours": [
    {
      "id": "uk-office",
      "name": "UK office hours",
      "timezone": "Europe/London",
      "intervals": [
        {
          "weekdays": [
            "mon"
          ],
          "start": "09:00",
          "end": "18:00"
        }
      ]
    }
  ],
  "nodes": [
    {
      "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "type": "level",
      "targets": [
        {
          "type": "user",
          "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71"
        }
      ],
      "escalate_after": "15m",
      "raise_urgency": true,
      "conditions": [
        {
          "type": "working_hours",
          "working_hours_id": "string",
          "active": true,
          "urgency": "standard",
          "when": {
            "id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
            "field": "/request/arguments/amount_cents",
            "operator": "exists",
            "value": {}
          }
        }
      ],
      "then": [
        {}
      ],
      "else": [
        {}
      ],
      "working_hours_id": "string",
      "standard_only": true
    }
  ],
  "repeat": {
    "times": 1,
    "after": "1h"
  },
  "document_version": 1,
  "warnings": [
    {
      "code": "team_members_cannot_decide",
      "team_id": "7ab8c8ec-7b2d-4fd6-9b52-752f9515eb71",
      "team_name": "string",
      "count": 1,
      "member_count": 1
    }
  ]
}