Skip to main content
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

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

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

Approvals and questions

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

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.
Environment changes apply to new processes. TZ defaults to UTC.

Schedules

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

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.