> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/guides/using-orbit-samples).

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`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://api.orbit.devotel.io/api/v1/public/callbacks/tkn_0c1d3e5f7a" \
    -H "X-API-Key: dv_test_sk_YOUR_KEY"
  ```

  ```typescript Node.js theme={null}
  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());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://api.orbit.devotel.io/api/v1/public/callbacks/tkn_0c1d3e5f7a/status" \
    -H "X-API-Key: dv_test_sk_YOUR_KEY"
  ```

  ```typescript Node.js theme={null}
  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());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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 '{}'
  ```

  ```typescript Node.js theme={null}
  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());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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" }'
  ```

  ```typescript Node.js theme={null}
  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());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "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.

```json 404 theme={null}
{
  "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:

```json 429 theme={null}
{
  "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"
  }
}
```