Oncall API

Oncall endpoints exposed by the Devotel CPaaS API Base path: /api/v1/oncall Endpoint count: 4

title: “Resolve rotations and plan escalations” description: “Model who is on call at any instant, and flatten an escalation policy into the ordered page timeline an incident driver would walk — as pure compute, with no pages sent.”

Resolve rotations and plan escalations

On-call tooling and the incident driver both live behind these two endpoints — the call resolves who is accountable at a given instant, and the plan flattens the escalation ladder you would walk when an incident refuses an ACK. Both are pure compute: nothing is persisted, no pages are sent, and no state changes. An incident driver (the webhook-worker escalation scheduler) still fires pages through the notify channel downstream. Resolve a rotation. POST /api/v1/oncall/resolve answers “who is on call now” — a rotation is a fixed-length shift schedule anchored to an absolute start (anchor), with members rotating through it in order.

{
  "data": {
    "rotation_name": "core-rotation",
    "at": "2026-08-01T12:00:00.000Z",
    "on_call": "+14155552671",
    "shift_index": 12,
    "shift_start": "2026-07-31T12:00:00.000Z",
    "shift_end": "2026-08-01T12:00:00.000Z",
    "next_on_call": "+14155559900",
    "next_handoff_at": "2026-08-01T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_resolve",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Plan an escalation. POST /api/v1/oncall/escalation/plan flattens the policy into the ordered pages timeline: each step names a target (a live rotation resolved at the page’s fire instant, or a static member list), the channels paged, and the escalate_after_seconds window before the next step. Each layer of the walk fires at a cumulative offsetSeconds from the incident start; policy.repeat loops the whole policy that many extra times if no step is ever acknowledged.

{
  "data": {
    "policy_name": "core-support",
    "start_at": "2026-08-01T12:00:00.000Z",
    "total_pages": 4,
    "pages": [
      {
        "round": 0,
        "step": 0,
        "offset_seconds": 0,
        "fire_at": "2026-08-01T12:00:00.000Z",
        "targets": ["+14155552671"],
        "channels": ["sms"]
      },
      {
        "round": 0,
        "step": 1,
        "offset_seconds": 300,
        "fire_at": "2026-08-01T12:05:00.000Z",
        "targets": ["oncall-secondary"],
        "channels": ["voice", "sms"]
      }
    ]
  },
  "meta": {
    "request_id": "req_plan",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Rotation targets resolve at each page’s fire instant, so a hand-off that lands mid-escalation reaches the right human.

SDK surface bridge — List the on-call rotation and take a live skip-rank claim — both read (or mutate) through the SDK escape hatch with the tenant’s live key.

These three tabs mirror SDK status and coverage. Python fronts client.request, Go fronts client.Request, and TS fronts fetch-TS — each with the live key.

List the on-call rotation

fetch-TS (Node SDK style)

const res = await fetch('https://api.orbit.devotel.io/api/v1/telephony/carriers/oncall', {
  method: 'GET',
  headers: {
'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

client.request

r = requests.get("https://api.orbit.devotel.io/api/v1/telephony/carriers/oncall", headers={ "X-API-Key": os.environ["ORBIT_API_KEY"] })
print(r.json())

client.Request

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/telephony/carriers/oncall", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

Claim the next slot (skip cycle)

fetch-TS (Node SDK style)

const res = await fetch('https://api.orbit.devotel.io/api/v1/telephony/carriers/oncall/skip-rank', {
  method: 'POST',
  headers: {
'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "cycle": "next"
},
})
console.log(await res.json())

client.request

r = requests.post("https://api.orbit.devotel.io/api/v1/telephony/carriers/oncall/skip-rank", json={
  "cycle": "next"
}, headers={ "X-API-Key": os.environ["ORBIT_API_KEY"] })
print(r.json())

client.Request

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/telephony/carriers/oncall/skip-rank", bytes.NewBuffer([]byte(`{
  "cycle": "next"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Plan escalation

POST /api/v1/oncall/escalation/plan

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/oncall/escalation/plan" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/oncall/escalation/plan', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/oncall/escalation/plan", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/oncall/escalation/plan", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/oncall/escalation/plan')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/oncall/escalation/plan');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "rotation_name": "core-rotation",
    "at": "2026-08-01T12:00:00.000Z",
    "on_call": "+14155552671",
    "shift_index": 12,
    "shift_start": "2026-07-31T12:00:00.000Z",
    "shift_end": "2026-08-01T12:00:00.000Z",
    "next_on_call": "+14155559900",
    "next_handoff_at": "2026-08-01T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_resolve",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Tick incident

POST /api/v1/oncall/incident/tick

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/oncall/incident/tick" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/oncall/incident/tick', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/oncall/incident/tick", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/oncall/incident/tick", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/oncall/incident/tick')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/oncall/incident/tick');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "rotation_name": "core-rotation",
    "at": "2026-08-01T12:00:00.000Z",
    "on_call": "+14155552671",
    "shift_index": 12,
    "shift_start": "2026-07-31T12:00:00.000Z",
    "shift_end": "2026-08-01T12:00:00.000Z",
    "next_on_call": "+14155559900",
    "next_handoff_at": "2026-08-01T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_resolve",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Transition incident

POST /api/v1/oncall/incident/transition

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/oncall/incident/transition" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/oncall/incident/transition', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/oncall/incident/transition", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/oncall/incident/transition", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/oncall/incident/transition')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/oncall/incident/transition');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "rotation_name": "core-rotation",
    "at": "2026-08-01T12:00:00.000Z",
    "on_call": "+14155552671",
    "shift_index": 12,
    "shift_start": "2026-07-31T12:00:00.000Z",
    "shift_end": "2026-08-01T12:00:00.000Z",
    "next_on_call": "+14155559900",
    "next_handoff_at": "2026-08-01T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_resolve",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Resolve oncall

POST /api/v1/oncall/resolve

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/oncall/resolve" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/oncall/resolve', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/oncall/resolve", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/oncall/resolve", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/oncall/resolve')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/oncall/resolve');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "rotation_name": "core-rotation",
    "at": "2026-08-01T12:00:00.000Z",
    "on_call": "+14155552671",
    "shift_index": 12,
    "shift_start": "2026-07-31T12:00:00.000Z",
    "shift_end": "2026-08-01T12:00:00.000Z",
    "next_on_call": "+14155559900",
    "next_handoff_at": "2026-08-01T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_resolve",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

API Reference

All Endpoints

Oncall API

Oncall API

title: “Resolve rotations and plan escalations” description: “Model who is on call at any instant, and flatten an escalation policy into the ordered page timeline an incident driver would walk — as pure compute, with no pages sent.”

Resolve rotations and plan escalations

SDK surface bridge — List the on-call rotation and take a live skip-rank claim — both read (or mutate) through the SDK escape hatch with the tenant’s live key.

List the on-call rotation

Claim the next slot (skip cycle)

Plan escalation

Tick incident

Transition incident

Resolve oncall

​Oncall API

​title: “Resolve rotations and plan escalations” description: “Model who is on call at any instant, and flatten an escalation policy into the ordered page timeline an incident driver would walk — as pure compute, with no pages sent.”

​Resolve rotations and plan escalations

​SDK surface bridge — List the on-call rotation and take a live skip-rank claim — both read (or mutate) through the SDK escape hatch with the tenant’s live key.

​List the on-call rotation

​Claim the next slot (skip cycle)

​Plan escalation

​Tick incident

​Transition incident

​Resolve oncall

Oncall API

title: “Resolve rotations and plan escalations” description: “Model who is on call at any instant, and flatten an escalation policy into the ordered page timeline an incident driver would walk — as pure compute, with no pages sent.”

Resolve rotations and plan escalations

SDK surface bridge — List the on-call rotation and take a live skip-rank claim — both read (or mutate) through the SDK escape hatch with the tenant’s live key.

List the on-call rotation

Claim the next slot (skip cycle)

Plan escalation

Tick incident

Transition incident

Resolve oncall