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

# Hosted chat and workspace

> Conversations, approvals, files, and workspace controls for a hosted agent.

Paths are relative to `https://inkbox.ai/api/v1/identities/my-agent/hosting`. Use an admin-scoped API key in `X-API-Key`. The identity's own key can read only `GET /workspace`.

## Conversations

| Method and path | Purpose |
| - | - |
| `GET /chat/conversations` | List conversations. Optional `origin` (`chat`, `communication`, or `schedule`), `after`, and `limit` (1–100, default 50). |
| `POST /chat/conversations` | Create a conversation with an optional `title`. |
| `GET /chat/conversations/{id}` | Read a snapshot. |
| `PATCH /chat/conversations/{id}` | Update `title` or `permission_mode`. |
| `GET /chat/conversations/{id}/messages` | Read older items with `snapshot` and `after`. |
| `POST /chat/conversations/{id}/turns` | Send a message. |
| `GET /chat/conversations/{id}/turns/{turn_id}` | Read a turn. |
| `POST /chat/conversations/{id}/turns/{turn_id}/cancel` | Request cancellation. |
| `GET /chat/conversations/{id}/events` | Read events as JSON, or as SSE with `Accept: text/event-stream`. |
| `POST /chat/conversations/{id}/interactions/{interaction_id}/response` | Answer an approval or question. |

Send an `Idempotency-Key` header when you create, update, send, cancel, answer, or upload. Retry a lost response with the same key and body.

A conversation runs one turn at a time. Another submission returns `409 conversation_busy`. Conversations started by incoming communications or schedules are read-only.

## Send a message

```json theme={null}
{
  "content": [
    {"type": "text", "text": "Summarize these notes."},
    {"type": "file", "file_id": "00000000-0000-4000-8000-000000000003"}
  ],
  "model": "gpt-6.1-sol"
}
```

Text is limited to 32,768 UTF-8 bytes. `model` is optional: `gpt-6-luna`, `gpt-6.1-terra`, `gpt-6.1-sol`, or `gpt-6-astra`. When omitted, the turn uses the agent's [`default_model`](https://inkbox.ai/docs/api/identities/hosting#read-hosting). Check `capabilities.model_selection` before choosing a model.

Sending a message starts a stopped computer. Reading does not.

Turn `status` is `queued`, `running`, `waiting_for_input`, `cancelling`, `completed`, `failed`, `cancelled`, or `outcome_unknown`. A blocked or failed turn can include a `blocker` with `code`, `retryable`, and suggested `actions`. Do not automatically resubmit an `outcome_unknown` turn.

## Tool permissions

`permission_mode` is `ask` (default) or `yolo`. In `ask`, each tool request creates an approval. In `yolo`, tool requests are approved automatically. A change applies to future turns.

Incoming communications and scheduled runs always approve tool requests automatically. Contact rules, data access, and quotas apply in every mode.

## Snapshots and events

1. Read the snapshot. Render its `items`, `pending_interactions`, and `current_turn`.
2. Fetch older items from `/messages` with `snapshot` set to the `snapshot_token` and `after` set to `next_cursor`.
3. Read events after the snapshot's `event_cursor`. To resume, pass the last event's `cursor` as `after` or `Last-Event-ID`.
4. Merge resources by `id` and `revision`. Order them by `created_sequence`.

After `410 event_cursor_expired` or a `stream.reset` event, read a new snapshot. Snapshot tokens expire after 30 minutes.

| Event | Meaning |
| - | - |
| `message.created`, `message.delta`, `message.completed` | A message. `message.delta` carries appended `text`. |
| `turn.updated` | Turn status and any `blocker`. |
| `tool.started`, `tool.updated`, `tool.completed` | Tool activity. |
| `interaction.created`, `interaction.updated` | An approval or question. |
| `artifact.created` | A file produced by the agent. |

## Approvals and questions

```json theme={null}
{
  "expected_version": 1,
  "response": {"kind": "approval", "decision": "approve_once"}
}
```

An approval `decision` is `approve_once` or `deny`. A question response is `{"kind": "question", "answers": {...}}`, keyed by field ID. Select fields take choice IDs, and multi-select fields take an array. Interactions expire at `expires_at`. Only the first valid response is accepted.

## Files

`POST /chat/files` uploads an attachment with `name`, `media_type`, and `data_base64`. Attachments are limited to 5 MB. Reference the returned `file.file_id` in a turn once it is available.

`GET /chat/files/{file_id}` returns metadata. `GET /chat/files/{file_id}/content` returns `data_base64`. Files produced by the agent use the same endpoints.

## Workspace

| Method and path | Purpose |
| - | - |
| `GET /workspace` | Computer state, agent readiness, capabilities, and allowed actions. |
| `POST /workspace/actions/start` or `/stop` | Start or stop the computer. Returns an operation ID. |
| `GET /workspace/operations/{operation_id}` | Read operation progress. |
| `GET /workspace/usage` | Current CPU, memory, and disk usage. |
| `GET /workspace/usage/history?window=24h` | Usage history. Windows are `1h`, `24h`, `7d`, and `30d`. |
| `GET /workspace/environment` | Read environment variables. Secret values are masked. |
| `PUT /workspace/environment` | Update environment variables. |
| `GET /workspace/terminals` | List terminal sessions. |
| `POST /workspace/terminals` | Create a terminal with optional `argv`, `cwd`, and `pty`. |
| `POST /workspace/terminals/{id}/ticket` | Get a ticket to attach to a terminal. |
| `POST /workspace/terminals/{id}/close` | Close a terminal. |

Start, stop, and terminal creation and closing take an `Idempotency-Key`. Start the computer before creating a terminal. Stop ends running programs and keeps files.

```json theme={null}
{
  "expected_version": 3,
  "set": {"TZ": {"value": "Europe/London", "secret": false}},
  "remove": []
}
```

Environment changes apply to new processes. `TZ` defaults to `UTC`.

## Schedules

| Method and path | Purpose |
| - | - |
| `GET /workspace/schedules` | List schedules and scheduling `capabilities`. |
| `POST /workspace/schedules` | Create a schedule. |
| `PUT /workspace/schedules/{id}` | Update, pause, or resume a schedule. |
| `DELETE /workspace/schedules/{id}` | Delete a schedule. |
| `POST /workspace/schedules/preview` | Preview upcoming runs for a `timing`. |
| `GET /workspace/schedules/{id}/occurrences` | Read run history. |

```json theme={null}
{
  "expected_revision": 0,
  "fields": {
    "name": "Morning digest",
    "task": {"kind": "prompt", "prompt": "Summarize today's inbox."},
    "timing": {"kind": "cron", "expression": "0 9 * * *", "timezone": "UTC"}
  }
}
```

Writes take an `Idempotency-Key` and the schedule's current `expected_revision` (`0` to create). `DELETE` takes the same body with empty `fields`. `timing.kind` is `cron` with `expression`, `interval` with `seconds`, or `once` with `at`.

Pause with `{"fields": {"enabled": false}}`. Pausing and deleting work while the computer is stopped. Creating, editing, and resuming require a running agent.

A schedule's `registration_status` is `pending`, `registered`, or `error`. An error includes a `registration_error`. Scheduled runs approve tool requests automatically.

## SDK and CLI

```python theme={null}
import os
from inkbox import Inkbox

with Inkbox(api_key=os.environ["INKBOX_API_KEY"]) as inkbox:
    workspace = inkbox.identities.workspace("my-agent")
    conversation = workspace.create_conversation("Inbox review", idempotency_key="create-inbox-review")
    turn = workspace.send(
        conversation["id"],
        [{"type": "text", "text": "Summarize my inbox"}],
        idempotency_key="inbox-review-turn",
        model="gpt-6.1-sol",
    )
```

```typescript theme={null}
import { Inkbox } from "@inkbox/sdk";

const inkbox = new Inkbox({ apiKey: process.env.INKBOX_API_KEY! });
const workspace = inkbox.identities.workspace("my-agent");
const conversation = await workspace.createConversation("Inbox review", "create-inbox-review");
const turn = await workspace.send(conversation.id, [{ type: "text", text: "Summarize my inbox" }], "inbox-review-turn", "gpt-6.1-sol");
```

In the CLI, run `inkbox identity hosting chat --help` and `inkbox identity hosting workspace --help`. `inkbox identity hosting chat events <handle> <conversation> --follow` streams events as JSON lines.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.