Status page

Worked status-page samples

The operations below document each route’s query and path parameters; this overlay walks the integration an embedder actually ships: read the feed → open one incident’s timeline → optionally parse the RSS → wire up the subscriber flow. The whole surface is unauthenticated — a status page is a public trust signal — so none of the calls need X-API-Key, and every read is edge-cached (s-maxage=60, so a 60-second poll interval is pointless; polls on a one-to-two-minute cadence hit the edge for free). Read and incident-write are split across roles on purpose: anyone with the URL can render the page, while publishing or updating an incident is a tenant-authenticated control-plane action from the dashboard Settings → Platform status surface (the status-page guide walks that console flow). This page documents the public read and subscriber surface — there is no API-key-gated incident-create endpoint to hand to your customers’ browsers. Every JSON response follows the same { data, meta } envelope — data carries the payload, meta carries the request_id and timestamp. Quote meta.request_id when you report a bad payload; support can trace the origin read from it.

1. Render the incident feed

GET /api/v1/public/incidents returns the platform’s declared incidents over a look-back window (days 1–365, default 90), newest first. Filter by component or status when your page needs a shard — a voice-only status strip, a resolved-incidents archive.

curl "https://api.orbit.devotel.io/api/v1/public/incidents?days=30&component=voice-sip&status=identified"

const url = new URL(
  "https://api.orbit.devotel.io/api/v1/public/incidents",
);
url.searchParams.set("days", "30");
url.searchParams.set("component", "voice-sip");
url.searchParams.set("status", "identified");
const res = await fetch(url);
console.log(await res.json());

200

{
  "data": {
    "incidents": [
      {
        "id": "inc_01JSTATUS",
        "title": "SMS delivery delays on US routes",
        "body": "Inbound MT traffic is delivering with elevated latency while the route is re-routed.",
        "status": "identified",
        "impact": "degraded",
        "affected_components": ["sms-us", "txt-webhooks"],
        "started_at": "2026-09-08T14:25:11Z",
        "scheduled_for": null,
        "scheduled_until": null,
        "resolved_at": null,
        "updated_at": "2026-09-08T16:02:41Z"
      }
    ],
    "window_days": 30
  },
  "meta": {
    "request_id": "req_stpg_feed_1",
    "timestamp": "2026-09-08T16:05:00Z"
  }
}

Empty returns look like {"incidents": []} — render your all-good banner rather than branch-crashing on a null.

2. Open one incident’s timeline

GET /api/v1/public/incidents/{id} returns the same row plus its status-update timeline (newest first, capped at the 100 most recent updates). Follow the lifecycle as it moves investigating → identified → monitoring → resolved — an unknown id returns a plain 404.

curl "https://api.orbit.devotel.io/api/v1/public/incidents/inc_01JSTATUS"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/public/incidents/inc_01JSTATUS",
);
if (!res.ok && res.status !== 404) {
  throw new Error(`incident detail failed: ${res.status}`);
}
console.log(await res.json());

200

{
  "data": {
    "id": "inc_01JSTATUS",
    "title": "SMS delivery delays on US routes",
    "body": "Inbound MT traffic is delivering with elevated latency while the route is re-routed.",
    "status": "monitoring",
    "impact": "degraded",
    "affected_components": ["sms-us", "txt-webhooks"],
    "started_at": "2026-09-08T14:25:11Z",
    "scheduled_for": null,
    "scheduled_until": null,
    "resolved_at": null,
    "updated_at": "2026-09-08T17:10:22Z",
    "updates": [
      {
        "id": "upd_01JSTATUSC3",
        "status": "monitoring",
        "body": "Alternative route is passing traffic; watching DLR latency for another hour.",
        "created_at": "2026-09-08T17:10:22Z"
      },
      {
        "id": "upd_01JSTATUSC2",
        "status": "identified",
        "body": "Root cause isolated to the primary US route; re-route in progress.",
        "created_at": "2026-09-08T16:02:41Z"
      },
      {
        "id": "upd_01JSTATUSC1",
        "status": "investigating",
        "body": "Elevated SMS delivery latency on US routes; investigating.",
        "created_at": "2026-09-08T14:25:11Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_stpg_detail_1",
    "timestamp": "2026-09-08T17:15:00Z"
  }
}

3. Parse the RSS feed (aggregators / uptime widgets)

GET /api/v1/public/incidents.rss returns the most recent 50 incidents as RSS 2.0 (application/rss+xml). Item titles are prefixed with the current status — [resolved] reads as history, [investigating] as live. Treat the feed as a convenience for readers and polling aggregators; a JSON client should prefer the filtered list op above.

curl "https://api.orbit.devotel.io/api/v1/public/incidents.rss"

const feed = await fetch(
  "https://api.orbit.devotel.io/api/v1/public/incidents.rss",
).then((res) => res.text());
console.log(feed.startsWith("<?xml") ? "feed OK" : "unexpected body");

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
<channel>
  <title>Orbit Status</title>
  <link>https://status.orbit.devotel.io</link>
  <description>Incident history for the Orbit CPaaS platform.</description>
  <language>en-us</language>
  <item>
    <title>[monitoring] SMS delivery delays on US routes</title>
    <link>https://status.orbit.devotel.io/incidents/inc_01JSTATUS</link>
    <guid isPermaLink="true">https://status.orbit.devotel.io/incidents/inc_01JSTATUS</guid>
    <pubDate>Tue, 08 Sep 2026 14:25:11 GMT</pubDate>
    <description>Status: monitoring · Impact: degraded · Affecting: sms-us, txt-webhooks</description>
  </item>
</channel>
</rss>

POST /api/v1/public/statuspage/subscribers starts a double-opt-in flow: the reader (or your embedded widget) submits an email, an out-of-band confirmation email lands, and the body answers with status: "pending_confirmation" and HTTP 202. A repeat subscribe for an already-confirmed address is idempotent — it answers status: "already_subscribed" with HTTP 200 and does not re-email, so a double-clicked widget submit is safe. The route is rate-limited per IP — map a 429 to a retry-after backoff.

curl -X POST "https://api.orbit.devotel.io/api/v1/public/statuspage/subscribers" \
  -H "Content-Type: application/json" \
  -d '{"email": "oncall@custco.example", "name": "On-call bridge"}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/public/statuspage/subscribers",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email: "oncall@custco.example",
      name: "On-call bridge",
    }),
  },
);
if (res.status === 202) {
  console.log("double-opt-in pending confirmation");
} else if (res.status === 200) {
  console.log("already subscribed");
}

202

{
  "data": {
    "status": "pending_confirmation",
    "message": "Check your email for a confirmation link."
  },
  "meta": {
    "request_id": "req_stpg_sub_1",
    "timestamp": "2026-09-08T17:20:00Z"
  }
}

The confirm link lands at <api-host>/api/v1/public/statuspage/subscribers/confirm/{token} — a GET, because email clients open links with GET. It flips the subscription to confirmed (or answers already_confirmed on a repeat click / unknown token, both as an idempotent success envelope).

5. Render one-click unsubscribe

Every incident notification carries a one-click unsubscribe at GET /api/v1/public/statuspage/subscribers/unsubscribe/{token}. It returns {"status": "unsubscribed"} on the first click and keeps returning the idempotent success {"status": "already_unsubscribed"} on any later click — so your embedded unsubscribe page can render without worrying about the second-tap double-debug. A fresh subscribe re-creates the row cleanly; no manual dedupe work.

Errors worth branching on

These five failures cover the status POST (POST /api/v1/status-page/updates), which every incident flow fires. Each block below is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface for the same five classes. For the platform-wide decision table these branches plug into, see the error handling guide.

401 — Unauthorized

  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "The API key is invalid, expired, or lacks the required scope.",
      "status": 401
    },
    "meta": {
      "request_id": "req_statuspaa1",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 401 on this page is the bearer key failing before the route ran — it never means the resource is wrong. Rotate the key or re-mint the scoped token; retrying the same request changes nothing.

403 — Forbidden

  {
    "error": {
      "code": "FORBIDDEN",
      "message": "The key is valid but does not have the scope this operation requires.",
      "status": 403
    },
    "meta": {
      "request_id": "req_statuspaa1f",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 403 means the key authenticated but the operation is gated by scope — check the key’s scopes on the developer page; a 403 is never a data-not-found shape.

422 — Schema

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": { "field": "state", "value": "glitch", "expected": "one of operational, degraded, partial_outage, major_outage" }
    },
    "meta": {
      "request_id": "req_statuspab2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and resend with an allowed state value instead of blind-retrying the same body.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_statuspac3",
      "timestamp": "2026-09-03T12:00:00Z",
      "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
    }
  }

The Retry-After header and error.details.retry_after are both set on every 429 — resend the SAME request after the lower of the two.

404 — Not found

  {
    "error": {
      "code": "STATUS_PAGE_COMPONENT_UNKNOWN",
      "message": "The component id referenced does not exist on the published status page.",
      "status": 404,
      "details": { "component_id": "cmp_0192" }
    },
    "meta": {
      "request_id": "req_statuspad4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

List components first and bind ids on the current page config — a stale id never resolves.

60-second retry matrix

Class	Meaning	Branch response
401 `UNAUTHORIZED`	the bearer key itself fails	Surface. Rotate the key or re-mint the scoped token; do not retry the same request.
403 `FORBIDDEN`	the key lacks this operation’s scope	Surface. Fix the key’s scope set; a retry with the same key never heals it.
422 `VALIDATION_ERROR`	the payload does not match the schema	Fix, then resend intentionally. Branch on `error.details.field`; a blind retry repeats the same 422.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.
`STATUS_PAGE_COMPONENT_UNKNOWN` (404 not found)	List components first and bind ids on the current page config	Branch on `error.code`. A stale id never resolves.

API Reference

All Endpoints

Worked status-page samples

1. Render the incident feed

2. Open one incident’s timeline

3. Parse the RSS feed (aggregators / uptime widgets)

5. Render one-click unsubscribe

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

404 — Not found

60-second retry matrix

​Worked status-page samples

​1. Render the incident feed

​2. Open one incident’s timeline

​3. Parse the RSS feed (aggregators / uptime widgets)

​4. Subscribe a reader to incident emails

​5. Render one-click unsubscribe

​Errors worth branching on

​401 — Unauthorized

​403 — Forbidden

​422 — Schema

​429 — Rate

​404 — Not found

​60-second retry matrix

Worked status-page samples

1. Render the incident feed

2. Open one incident’s timeline

3. Parse the RSS feed (aggregators / uptime widgets)

4. Subscribe a reader to incident emails

5. Render one-click unsubscribe

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

404 — Not found

60-second retry matrix