> ## Documentation Index
> Fetch the complete documentation index at: https://continuum-three-olive.vercel.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Computer API (preview)

> Preview: create bots per client, manage their computers, and embed chat and computer control.

<Note>
  The **Continuum Bot API**, covering bots and computers, is preview. The client lifecycle routes and examples below describe the proposed phase 1 contract. Paths, JSON fields, token responses, stream events, and the SDK asset URL are subject to change. Obtain the deployed contract from your organization admin before running them. The Mac connection sheet is upcoming.
</Note>

Use this API when your application needs a bot that can work on a computer, retain a conversation, and appear inside your product. For model requests alone, use the separate [Inference API](/docs/apis/inference).

## Concepts

| Object   | Purpose                                                                                                   |
| -------- | --------------------------------------------------------------------------------------------------------- |
| Partner  | An integration within a Continuum organization, with its own keys, allowed origins, and usage attribution |
| Client   | A customer or internal workspace within a partner; may carry your application's external ID               |
| Bot      | A client-owned agent with a name, goal, model, effort defaults, and transcript                            |
| Computer | The bot's runtime and interactive desktop; it can wake or sleep independently of the transcript           |

The preview design scopes access and usage by partner and client. Inference usage and computer time are separate usage categories; per-client reporting will roll them up for the partner. Confirm quotas and computer pricing during onboarding. An inference subscription does not by itself provision partner computer access.

## Keys and client tokens

The upcoming Mac flow is **Bots → bot action menu → Connect to your app…**. It will create or select the partner, register allowed origins, issue a key, associate a client, and provide a snippet for the bot. Until available, ask your **organization admin** to provision preview access.

| Credential                 | Held by               | Purpose                                                                      |
| -------------------------- | --------------------- | ---------------------------------------------------------------------------- |
| Partner key, `cont_pk_…`   | Your backend          | Manage the authorized partner's clients, bots, computers, and token issuance |
| Client token, `cont_ct_…`  | Your browser or embed | Short-lived access scoped to one client                                      |
| Inference key, `cont_sk_…` | Your backend          | Call the existing inference endpoints                                        |

Partner keys are shown once. Store them as server secrets, grant only needed scopes, and revoke unused keys. Before issuing a client token, authenticate your user and check their access to the client. Do not let a browser choose an unchecked client ID. Use the issued expiry to refresh tokens through your backend; the preview client-token lifetime is not finalized. A client token is distinct from the two-minute phase 0 computer handoff described below.

## Preview routes

Every path in this table is relative to `COMPUTER_API_PREFIX`, defined once in the quickstart. All requests are JSON and use `Authorization: Bearer YOUR_PARTNER_KEY` from your backend. Browser access uses the scoped client-token contract supplied with preview access.

| Method                   | Relative path                                   | Purpose                                                                |
| ------------------------ | ----------------------------------------------- | ---------------------------------------------------------------------- |
| `POST`, `GET`            | `/clients`                                      | Create or list clients                                                 |
| `DELETE`                 | `/clients/:clientId`                            | Delete a client                                                        |
| `POST`, `GET`            | `/clients/:clientId/bots`                       | Create or list bots                                                    |
| `GET`, `PATCH`, `DELETE` | `/clients/:clientId/bots/:botId`                | Read, update, or delete a bot                                          |
| `POST`, `GET`            | `/clients/:clientId/bots/:botId/computer`       | Ensure or wake a computer; read status and available presleep snapshot |
| `POST`                   | `/clients/:clientId/bots/:botId/computer/sleep` | Sleep the computer                                                     |
| `POST`                   | `/clients/:clientId/bots/:botId/messages`       | Send a message                                                         |
| `GET`                    | `/clients/:clientId/bots/:botId/transcript`     | Read transcript entries; proposed SSE negotiation below                |
| `POST`                   | `/clients/:clientId/tokens`                     | Issue a client token for an embed                                      |

Idempotency, rate limits, and tenant isolation are part of the preview contract. Confirm the deployed idempotency field or header before retrying writes. Keep one idempotency value per logical operation and reuse it only for that operation. Treat `429` as a signal to back off; partner and client limit values will be supplied with access.

## Preview quickstart

These curl examples show the intended sequence. Client and bot field names are illustrative until the preview schema is finalized. Run them on your backend. Set `CONTINUUM_PARTNER_KEY` securely first. Keep returned credentials out of logs.

### 1. Configure the endpoint and create a client

`COMPUTER_API_PREFIX` is the single prefix setting for all phase 1 examples. The phase 0 routes later on this page have a separate, existing contract.

```bash theme={"dark"}
CONTINUUM_ORIGIN="https://continuumcode.ai"
COMPUTER_API_PREFIX="/v1/partner"
COMPUTER_API_BASE="$CONTINUUM_ORIGIN$COMPUTER_API_PREFIX"

curl --fail-with-body "$COMPUTER_API_BASE/clients" \
  -H "Authorization: Bearer $CONTINUUM_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example client","externalId":"customer-123"}'
```

Copy the returned client ID into `CLIENT_ID`. Store its mapping to your application's customer ID on your backend.

### 2. Create a bot

```bash theme={"dark"}
CLIENT_ID="REPLACE_WITH_RETURNED_CLIENT_ID"

curl --fail-with-body "$COMPUTER_API_BASE/clients/$CLIENT_ID/bots" \
  -H "Authorization: Bearer $CONTINUUM_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Research assistant",
    "goal":"Research the client project and report findings.",
    "model":"gpt-5.6-sol",
    "effort":"high"
  }'
```

Use model and effort defaults approved for your partner. Save the returned bot ID.

### 3. Wake the computer

```bash theme={"dark"}
BOT_ID="REPLACE_WITH_RETURNED_BOT_ID"
BOT_URL="$COMPUTER_API_BASE/clients/$CLIENT_ID/bots/$BOT_ID"

curl --fail-with-body "$BOT_URL/computer" \
  -H "Authorization: Bearer $CONTINUUM_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

curl --fail-with-body "$BOT_URL/computer" \
  -H "Authorization: Bearer $CONTINUUM_PARTNER_KEY"
```

Waking can take time. Poll status with backoff until it reports readiness. A presleep snapshot shows the last captured desktop; it does not mean the computer is running.

### 4. Send a message

```bash theme={"dark"}
curl --fail-with-body "$BOT_URL/messages" \
  -H "Authorization: Bearer $CONTINUUM_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Open the project and summarize the next task."}'
```

Message acceptance is not turn completion. Follow the transcript for progress and results.

### 5. Read and stream the transcript

```bash theme={"dark"}
curl --fail-with-body "$BOT_URL/transcript" \
  -H "Authorization: Bearer $CONTINUUM_PARTNER_KEY"

curl --fail-with-body --no-buffer "$BOT_URL/transcript" \
  -H "Authorization: Bearer $CONTINUUM_PARTNER_KEY" \
  -H "Accept: text/event-stream"
```

The second request illustrates proposed SSE negotiation on the transcript route. The final stream path, event names, and reconnect cursor are pending. Use polling if streaming is not enabled. A transcript stream carries conversation entries; the computer view uses the dedicated relay transport. Browser `EventSource` cannot set an Authorization header, so use the preview SDK or a fetch-based SSE reader with the approved client-token flow.

### 6. Issue a client token and embed the bot

```bash theme={"dark"}
curl --fail-with-body "$COMPUTER_API_BASE/clients/$CLIENT_ID/tokens" \
  -H "Authorization: Bearer $CONTINUUM_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Return only the short-lived client token and necessary bot metadata to the authorized browser. Load the SDK URL supplied with preview access, then use this proposed component:

```html theme={"dark"}
<script type="module" src="REPLACE_WITH_PREVIEW_SDK_URL"></script>
<continuum-bot
  client-token="REPLACE_WITH_SHORT_LIVED_CLIENT_TOKEN"
  bot-id="REPLACE_WITH_BOT_ID">
</continuum-bot>
```

The component is intended to show chat and the computer view. The placeholder SDK URL is not a published asset. Supply tokens dynamically from your backend; do not hardcode them in a deployed page. The browser never receives your partner key or inference key.

### 7. Sleep the computer

```bash theme={"dark"}
curl --fail-with-body "$BOT_URL/computer/sleep" \
  -H "Authorization: Bearer $CONTINUUM_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Phase 0 compatibility and handoff security

Phase 0 already defines backend access for an admin-provisioned member and an owned, active, non-group bot. It uses a `cont_sk_` member key with `bot:drive` scope, an enabled organization policy, and `X-Partner-Origin` selecting a stored allowed origin. An ordinary inference key only has `inference:chat` and cannot drive a computer.

| Existing route                          | Behavior                                                                                       |
| --------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `POST /v1/bots/:id/messages`            | Send a message through the existing bot wake flow                                              |
| `GET /v1/bot-computer/access?botId=:id` | Issue a two-minute computer handoff                                                            |
| `WS /v1/bot-computer/relay`             | Cloud gateway for scoped computer frames and input                                             |
| `GET /v1/bot-computer/embed`            | Dedicated computer HTML; returns `503 partner_embed_unavailable` until its bundle is installed |
| `POST /v1/bot-computer/handback`        | End the partner grant and disconnect its streams                                               |

The browser connects to the cloud gateway with the `continuum.partner.computer.v1` and `bearer.HANDOFF_TOKEN` WebSocket subprotocols. Use the relay URL returned by access. Broad relay controller credentials and agent bearers stay in cloud. Wait for `subReady` before sending input. Phase 0 uses computer frames over the JPEG relay transport; it is not a general host, terminal, or network proxy.

Handoffs last **two minutes** and cannot renew themselves. Your backend must request another with its live drive key. A new issuance supersedes the prior organization grant. Key revocation, origin removal, handback, ownership loss, and expiry deny subsequent frames and input. Handback ends cloud partner access; it does not automatically resume the host's paused agent.

## Origins and CSP

Register exact HTTPS origins such as `https://portal.example.com`, with no path, trailing slash, wildcard, query, or fragment. Explicit localhost origins are only accepted in configured non-production environments. The origin header selects policy; it does not create an allowlist entry or replace authentication.

The phase 0 embed's `frame-ancestors` permits only its stored partner origins and itself. Other or invalid contexts retain `frame-ancestors 'none'`; the general app is not frame-enabled. Browser WebSocket origin checks remain bound to the selected partner origin or the dedicated gateway origin. Configure your page's own CSP to permit the approved SDK, frame, and connection URLs.

Keep credential responses uncached. Never log raw keys, client tokens, handoff query strings, or WebSocket authentication subprotocols. If using the phase 0 handoff query parameter for iframe navigation, redact it in access logs and use `Referrer-Policy: no-referrer`. A public transcript share does not grant computer control.

## Upcoming

| Phase   | Planned additions                                                                                                                                                                            |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Phase 2 | Signed webhooks with HMAC verification and retries; events `bot.turn.completed`, `bot.needs_attention`, `computer.state`, and `client.usage.threshold`; per-client usage and billing reports |
| Phase 3 | Partner SSO using signed identity to create client sessions; white-label embed name, logo, and theme; custom-domain support subject to rollout                                               |

Webhook registration routes, signature headers, delivery guarantees, SSO endpoints, and white-label settings are not a stable public contract yet. Use transcript polling or preview streaming while webhook delivery is upcoming.