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
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
- Read the snapshot. Render its
items,pending_interactions, andcurrent_turn. - Fetch older items from
/messageswithsnapshotset to thesnapshot_tokenandafterset tonext_cursor. - Read events after the snapshot’s
event_cursor. To resume, pass the last event’scursorasafterorLast-Event-ID. - Merge resources by
idandrevision. Order them bycreated_sequence.
410 event_cursor_expired or a stream.reset event, read a new snapshot. Snapshot tokens expire after 30 minutes.
Approvals and questions
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.
TZ defaults to UTC.
Schedules
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
inkbox identity hosting chat --help and inkbox identity hosting workspace --help. inkbox identity hosting chat events <handle> <conversation> --follow streams events as JSON lines.
