codai Hosts API

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.

GitHub OpenAPI

Operations 4

GET /v1/hosts List your devices currently connected as hosts #
GET /v1/hosts/stream Announce this device as a host (SSE) #
POST /v1/hosts/{deviceId}/exec Run one operation on a connected host #
POST /v1/hosts/exec/{reqId}/result Deliver the result of an exec request #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/codai-ro:codai-ro-hosts-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

codai-ro-hosts-api-openapi.yml Raw ↑
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