Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Codai Ro Hosts API
version: '1'
description: 'Operations tagged Hosts across 2 of this provider''s published API definitions: codai-ro-gateway-openapi.json, codai-ro-gateway-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://ai.codai.ro
description: Production
security:
- bearerAuth: []
tags:
- name: Hosts
description: 'Host relay for remote sessions: a phone (or any client) runs terminal and file operations on one of your desktop
devices that has codai desktop open — no SSH, no inbound port. Best-effort and NOT part of the public
shared-sessions protocol spec: nothing is persisted, an offline host fails fast and an unanswered request fails at
the client''s timeout.'
paths:
/v1/hosts:
get:
operationId: listHosts
tags:
- Hosts
summary: List your devices currently connected as hosts
description: 'Presence list of the caller''s devices that have an open `GET /v1/hosts/stream`. Presence lives in Redis with
a 45 s TTL refreshed by the stream''s 15 s heartbeat (an in-process map when Redis is not configured), so a
host that lost its connection disappears within 45 s. Sorted by `last_seen` descending. Only your own hosts
are ever listed — there is no cross-user host sharing in v1.'
parameters:
- $ref: '#/components/parameters/RequestId'
responses:
'200':
description: Connected hosts.
content:
application/json:
schema:
type: object
required:
- hosts
properties:
hosts:
type: array
items:
$ref: '#/components/schemas/HostPresence'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
servers:
- url: https://ai.codai.ro
description: Production
/v1/hosts/stream:
get:
operationId: streamHost
tags:
- Hosts
summary: Announce this device as a host (SSE)
description: 'Host side (codai desktop with "Serve as remote host", or the codai iPhone bridge). Opening this stream
registers the calling device (`x-codai-device`, implicitly registered if new) as an online host and delivers
`exec` requests aimed at it. Self-description travels in query params because a GET has no body. Events
(`event:` + JSON `data:`; no `id:` lines, no resume — a reconnect simply re-announces presence):
- `hello` — `{ device_id, heartbeat_ms: 15000, caps, environment_id }`, sent once on connect.
- `ping` — `{ t }` (epoch ms) every 15 s; each ping also refreshes the 45 s presence TTL.
- `exec` — `HostExecRequest`: `{ req_id, op, args, timeout_ms, label?, from_device_id, ts }`. Run the op and
answer with `POST /v1/hosts/exec/{req_id}/result` within `timeout_ms`.
The stream is closed by the server after 6 h; presence is cleared as soon as the connection aborts.
Ops are a fixed vocabulary: `shell {cmd, cwd?, timeout_ms?}`, `fs_read {path, max_bytes?}`,
`fs_write {path, content}`, `fs_list {path}`, `fs_roots {}`, `info {}` — their `args` are relayed verbatim —
and `iphone {tool, args?}` (hosts with cap `iphone`), whose `args` the gateway validates (`tool` matches
`^[a-z_]{1,64}$`, `args` is an object). The iPhone bridge registers `os=ios`, `caps=iphone,video` and the
environment that streams its screen as `env`.'
parameters:
- $ref: '#/components/parameters/RequestId'
- $ref: '#/components/parameters/DeviceHeader'
- name: os
in: query
required: false
description: Host operating system label; truncated to 40 chars.
schema:
type: string
maxLength: 40
examples:
- windows
- name: hostname
in: query
required: false
description: Host machine name; truncated to 120 chars.
schema:
type: string
maxLength: 120
examples:
- dragos-desktop
- name: roots
in: query
required: false
description: Comma-separated list of filesystem roots the host exposes; blanks dropped, max 32 entries.
schema:
type: string
examples:
- E:\gh,C:\Users\me\Projects
- name: caps
in: query
required: false
description: Comma-separated capabilities the host offers (`iphone`, `video`, `pty`, …); at most 16 entries, each matching `^[a-z0-9_-]{1,32}$`, duplicates dropped. A malformed list is a 400.
schema:
type: string
examples:
- iphone,video
- name: env
in: query
required: false
description: UUID of the environment that serves `video` / `pty` streams for this host over codai-relay. Not a uuid → 400.
schema:
type: string
format: uuid
examples:
- 7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f
responses:
'200':
description: 'SSE stream (`text/event-stream`, `cache-control: no-cache`).'
content:
text/event-stream:
schema:
type: string
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
servers:
- url: https://ai.codai.ro
description: Production
/v1/hosts/{deviceId}/exec:
post:
operationId: execOnHost
tags:
- Hosts
summary: Run one operation on a connected host
description: 'Client side. Publishes an `exec` request to the host''s stream and blocks until the host posts a result or
the timeout elapses (`timeout_ms`, default 60000, max 600000; the gateway waits an extra 2 s of grace). The
host''s `{ ok, result, error }` is returned verbatim with the `req_id`. The caller''s own device must be
identified with `x-codai-device` (it becomes `from_device_id` in the relayed request). Host and requester
must belong to the same user. A device you own that is not streaming → 409 `host_offline`; a device that is
not yours or does not exist → 404; no answer in time → 504 `host_timeout`.
Op `iphone` drives an iPhone through the codai iPhone bridge: `args = { tool, args? }` with the same tool names
as the local `codai-iphone` MCP (`screen`, `tap`, `swipe`, `type`, `open_app`, …). The host answers
`result = { data, image? }` where `image` is an optional `data:image/jpeg;base64,…` screenshot (≤ 1.5 MB; the
whole result ≤ 2 MB). Sensitive tools are refused by the bridge when called remotely.'
parameters:
- $ref: '#/components/parameters/RequestId'
- $ref: '#/components/parameters/DeviceHeader'
- name: deviceId
in: path
required: true
description: Device UUID of the target host (from `GET /v1/hosts`).
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HostExecBody'
responses:
'200':
description: The host answered (whether `ok` is true or false).
content:
application/json:
schema:
$ref: '#/components/schemas/HostExecResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: 'The device is yours but is not connected as a host right now (`code: host_offline`; open codai desktop with remote host on, or start the iPhone bridge).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'504':
description: 'The host did not answer within `timeout_ms` (`code: host_timeout`).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
servers:
- url: https://ai.codai.ro
description: Production
/v1/hosts/exec/{reqId}/result:
post:
operationId: postHostExecResult
tags:
- Hosts
summary: Deliver the result of an exec request
description: 'Desktop side. Completes the pending `POST /v1/hosts/{deviceId}/exec` identified by `reqId` (taken from the
`exec` event). The body is relayed to the requester verbatim, so `result` may be any JSON. The raw body may
not exceed 2,000,000 bytes. The caller must present `x-codai-device`. Ownership of `reqId` is not re-checked:
the id is an unguessable UUID handed only to the host. Posting for an unknown or already-completed `reqId`
still returns `{ ok: true }` — the frame is simply dropped.'
parameters:
- $ref: '#/components/parameters/RequestId'
- $ref: '#/components/parameters/DeviceHeader'
- name: reqId
in: path
required: true
description: The `req_id` from the `exec` event (UUID; malformed → 400).
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HostExecResultBody'
responses:
'200':
description: Accepted.
content:
application/json:
schema:
type: object
required:
- ok
properties:
ok:
type: boolean
enum:
- true
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
servers:
- url: https://ai.codai.ro
description: Production
components:
responses:
Unauthorized:
description: Missing, malformed, revoked or paused API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: The key is valid but not allowed to perform this action (model allow-list, role, ownership).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
PaymentRequired:
description: The subscription behind this key is inactive.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: No such resource, or it belongs to another account.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Malformed body or query; `details` holds the flattened field errors.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
HostOp:
type: string
description: Operation vocabulary hosts implement (codai desktop; `iphone` = the codai iPhone bridge, cap `iphone`).
enum:
- shell
- fs_read
- fs_write
- fs_list
- fs_roots
- info
- iphone
HostPresence:
type: object
title: Host presence
description: A device currently connected to `GET /v1/hosts/stream`.
required:
- device_id
- name
- platform
- os
- hostname
- roots
- caps
- environment_id
- since
- last_seen
properties:
device_id:
type: string
format: uuid
examples:
- 2b6d8c1e-4f3a-4e9b-9c0d-7a1e5f6b8c2d
name:
type:
- string
- 'null'
description: Device display name.
examples:
- codai desktop
platform:
type:
- string
- 'null'
description: Device platform (see `DevicePlatform`).
examples:
- desktop
os:
type:
- string
- 'null'
description: From the `os` query param of the stream, if given.
examples:
- windows
hostname:
type:
- string
- 'null'
examples:
- dragos-desktop
roots:
type: array
items:
type: string
description: Filesystem roots the host announced.
examples:
- - E:\gh
- C:\Users\me\Projects
caps:
type: array
items:
type: string
description: Capabilities the host announced with `caps=` (`iphone`, `video`, `pty`, …); empty when none.
examples:
- - iphone
- video
environment_id:
type:
- string
- 'null'
format: uuid
description: Environment that serves `video` / `pty` streams for this host over codai-relay (`env=` of the stream), or null.
examples:
- 7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f
since:
type: integer
description: Epoch ms when the current stream was opened.
examples:
- 1758616800000
last_seen:
type: integer
description: Epoch ms of the last heartbeat.
examples:
- 1758616845000
HostExecBody:
type: object
title: Host exec request body
required:
- op
properties:
op:
$ref: '#/components/schemas/HostOp'
args:
type: object
additionalProperties: true
default: {}
description: Op-specific arguments, relayed verbatim (e.g. `{ cmd, cwd?, timeout_ms? }` for `shell`, `{ path }` for `fs_list`). For `iphone` they must match `HostIphoneArgs` (`{ tool, args? }`), else 400.
examples:
- cmd: git status
cwd: E:\gh\codai
timeout_ms:
type: integer
minimum: 1000
maximum: 600000
description: How long to wait for the host. Default 60000.
examples:
- 30000
label:
type: string
maxLength: 200
description: Free-form label shown in the host UI.
examples:
- session grp8 · terminal
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- message
- type
- code
properties:
message:
type: string
description: Human-readable, provider names redacted.
type:
type: string
enum:
- invalid_request_error
- subscription_required
- rate_limit_error
- upstream_error
- server_error
code:
type: string
enum:
- bad_request
- invalid_api_key
- subscription_inactive
- forbidden
- not_found
- payload_too_large
- rate_limit_exceeded
- quota_exceeded
- upstream_error
- internal_error
- not_a_member
- lease_held
- seq_conflict
- host_offline
- host_timeout
- rules_refused
- search_unavailable
- task_not_confirmable
- slug_taken
- project_has_environments
- already_has_env
- not_enrollable
- not_byo
- invalid_transition
- already_member
- vm_per_dev_single_member
- last_owner
- insufficient_balance
- key_scope_forbidden
- assets_unavailable
- asset_not_found
- too_many_renders
- renders_unavailable
- timeline_too_long
- not_a_timeline
- invalid_cursor
- templates_unavailable
- url_blocked
- invalid_tokens
- unsupported_media
- kind_mismatch
- node_not_found
- invalid_pick
- duplicate_key
- unknown_var
- invalid_var_value
- unsupported_kind
- too_long
- stale
- not_supported_for_kind
- unsupported_format
- too_large
- not_implemented
- version_conflict
- settings_unavailable
- ai_label_required
- sandbox_concurrency_limit
- sandbox_busy
- sandbox_daily_limit
- invalid_ttl
- workspace_too_large
- sandbox_paused_limit
- sandbox_capacity
details:
description: Present on `bad_request` (flattened Zod field errors), `invalid_tokens` (`issues`) and `rules_refused` (`tool`, `rule_id`, `decision`). Other codes never forward details over HTTP.
type: object
additionalProperties: true
examples:
- error:
message: Invalid or missing API key.
type: invalid_request_error
code: invalid_api_key
HostExecResultBody:
type: object
title: Host exec result body
required:
- ok
properties:
ok:
type: boolean
description: Whether the op succeeded on the host.
result:
description: Any JSON produced by the op (e.g. `{ stdout, stderr, exit_code }` for `shell`); relayed as-is. Shape is defined by the desktop, not the gateway.
error:
type: string
maxLength: 4000
description: Human-readable failure reason when `ok` is false.
HostExecResponse:
type: object
title: Host exec response
required:
- req_id
- ok
- result
- error
properties:
req_id:
type: string
format: uuid
ok:
type: boolean
result:
description: The host's `result`, or `null` when absent.
error:
type:
- string
- 'null'
parameters:
RequestId:
name: x-request-id
in: header
required: false
description: Client correlation id; echoed back as `x-codai-trace-id` and persisted on the usage row.
schema:
type: string
maxLength: 128
DeviceHeader:
name: x-codai-device
in: header
required: true
description: Stable device UUID. Registers the device on first use (name/platform from `x-codai-device-name` / `x-codai-device-platform`) and selects the shared-sessions protocol.
schema:
type: string
format: uuid
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: codai_…
description: A codai API key (`codai_` prefix). Ephemeral tokens from `POST /v1/tokens` are accepted only by the media surfaces matching their scope (`/v1/realtime`, `/v1/audio/*`, `/v1/embeddings`).
x-refined-from:
- codai-ro-gateway-openapi.json
- codai-ro-gateway-openapi.yml