Public

Worked public samples

The endpoint list below documents every public route’s parameters; this overlay walks a callback-remember link the way the token holder actually uses it: look up the callback → check its status → cancel it → reschedule it. The {token} path segment is the public bearer handle Devotel mails to the customer; treat it like a read-once credential. Success envelopes are { data, meta }, error envelopes { error, meta } — the four shapes together are documented in How to read a worked sample. Every response carries meta.request_id. Quote the request id when you report an out-of-window token or a misfired cancel so support can trace the request end-to-end. Public endpoints accept the same sandbox key rule as the rest of the reference — run samples with a dv_test_sk_* key and never post a live token from a browser.

1. Look up a callback token

GET /api/v1/public/callbacks/{token} returns the callback’s arrival state — ok: true with status set to pending, running, succeeded, failed, or canceled. It also reports whether a cancel and a reschedule request would still be accepted, so your confirmation page can hide an action that would 409.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/public/callbacks/tkn_0c1d3e5f7a" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/public/callbacks/tkn_0c1d3e5f7a",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "id": "cbk_01J8Q2WZP4Q3R8YW7T6S",
    "status": "pending",
    "attempts": 1,
    "max_attempts": 3,
    "next_attempt_at": "2026-08-26T12:30:00.000Z",
    "scheduled_for": "2026-08-26T12:30:00.000Z",
    "caller": "+1234***5678",
    "can_cancel": true,
    "can_reschedule": true
  },
  "meta": {
    "request_id": "req_pub_get",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

caller masks the calling number for screen readers and logs; the full E.164 number only resolves inside your tenant-scoped callback list.

2. Check a callback’s status

GET /api/v1/public/callbacks/{token}/status answers the same envelope without the embedded PII — use it for a barebones “still pending” check on the confirmation page before you offer the cancel button.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/public/callbacks/tkn_0c1d3e5f7a/status" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/public/callbacks/tkn_0c1d3e5f7a/status",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "status": "pending",
    "attempts": 1,
    "max_attempts": 3,
    "next_attempt_at": "2026-08-26T12:30:00.000Z",
    "can_cancel": true,
    "can_reschedule": true
  },
  "meta": {
    "request_id": "req_pub_status",
    "timestamp": "2026-08-26T12:00:04.000Z"
  }
}

3. Cancel the callback

POST /api/v1/public/callbacks/{token}/cancel stops the remaining retry wins and flips the callback to canceled. It works even after an attempt already ran — already_canceled true` tells you a previous cancel-won, and the request is idempotent.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/public/callbacks/tkn_0c1d3e5f7a/cancel" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/public/callbacks/tkn_0c1d3e5f7a/cancel",
  {
    method: "POST",
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "ok": true,
    "status": "canceled",
    "already_canceled": false
  },
  "meta": {
    "request_id": "req_pub_cancel",
    "timestamp": "2026-08-26T12:05:00.000Z"
  }
}

4. Reschedule the callback

POST /api/v1/public/callbacks/{token}/reschedule moves the callback to a new scheduled_for and resets the retry ladder. Rotate scheduled_for — send the new timestamp when you re-issue the token.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/public/callbacks/tkn_0c1d3e5f7a/reschedule" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_for": "2026-08-27T09:00:00.000Z" }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/public/callbacks/tkn_0c1d3e5f7a/reschedule",
  {
    method: "POST",
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
    body: JSON.stringify({
      scheduled_for: "2026-08-27T09:00:00.000Z",
    }),
  },
);
console.log(await res.json());

200

{
  "data": {
    "ok": true,
    "status": "pending",
    "scheduled_for": "2026-08-27T09:00:00.000Z"
  },
  "meta": {
    "request_id": "req_pub_reschedule",
    "timestamp": "2026-08-26T12:06:00.000Z"
  }
}

5. Errors

Errors follow the { error, meta } envelope. Two failures every token holder hits: 404 — token not found or out of window. A guessed token was never issued or the callback window already closed. Do not retry.

404

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "No callback with that access token exists.",
    "status": 404
  },
  "meta": {
    "request_id": "req_pub_err",
    "timestamp": "2026-08-26T12:07:00.000Z"
  }
}

429 — token hydra-throttled. A public link that is punched 60 seconds apart returns a plain rate-limit so a runaway browser refresh is bounded:

429

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Public token refresh is bounded to one request per window.",
    "status": 429
  },
  "meta": {
    "request_id": "req_pub_err2",
    "timestamp": "2026-08-26T12:07:30.000Z"
  }
}

API Reference

All Endpoints

Worked public samples

1. Look up a callback token

2. Check a callback’s status

3. Cancel the callback

4. Reschedule the callback

5. Errors

​Worked public samples

​1. Look up a callback token

​2. Check a callback’s status

​3. Cancel the callback

​4. Reschedule the callback

​5. Errors

Worked public samples

1. Look up a callback token

2. Check a callback’s status

3. Cancel the callback

4. Reschedule the callback

5. Errors