codai Devices API

Register, list and manage the devices bound to your account.

GitHub OpenAPI

Operations 7

GET /v1/devices/me/dispatch Pending dispatch for this device across all sessions #
GET /v1/devices List your devices #
GET /v1/devices/plugins List the audio plugins installed on your devices #
PUT /v1/devices/{id}/plugins Replace a device's audio plugin inventory #
PATCH /v1/devices/{id} Update a device's push token or capabilities #
DELETE /v1/devices/{id} Revoke one of your devices #
POST /v1/keys/self/revoke Revoke the calling API key (sign out) #

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-devices-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-devices-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Codai Ro Devices API
  version: '1'
  description: 'Operations tagged Devices 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: Devices
  description: Register, list and manage the devices bound to your account.
paths:
  /v1/devices/me/dispatch:
    get:
      operationId: getMyDispatchInbox
      tags:
      - Devices
      summary: Pending dispatch for this device across all sessions
      description: 'Aggregated inbox for the calling device (`x-codai-device` required, else `400`):

        every pending (`applied=false`) control dispatched at it, across all unarchived

        sessions you OWN, grouped by session with `session_key` and `title` so an executor

        can start without a second lookup. Never lease-gated — drain first, then claim.

        Replaces polling `GET /v1/sessions/{id}/controls?target=me` per session. Controls

        are capped at `limit` (default 200, max 500) and the global pending scan at 2000 rows.

        A `mode:"open"` handoff control carries `mode: "open"`: open the session, run nothing.'
      parameters:
      - $ref: '#/components/parameters/DeviceHeader'
      - name: x-codai-device-name
        in: header
        required: false
        description: Human-readable device name used when the device is first registered (truncated to 120 chars).
        schema:
          type: string
          maxLength: 120
      - name: x-codai-device-platform
        in: header
        required: false
        description: Platform recorded on first registration; unknown values become `agent`.
        schema:
          type: string
          enum:
          - android
          - ios
          - web
          - desktop
          - cli
          - agent
      - $ref: '#/components/parameters/RequestId'
      - name: limit
        in: query
        required: false
        description: Max controls returned in total. Default 200, max 500.
        schema:
          type: integer
          minimum: 0
          maximum: 500
          default: 200
      responses:
        '200':
          description: Pending controls grouped by session (empty `sessions` when none).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionDispatchInbox'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    servers:
    - url: https://ai.codai.ro
      description: Production
  /v1/devices:
    get:
      operationId: listDevices
      tags:
      - Devices
      summary: List your devices
      description: 'Returns every device registered under the calling user, most recently seen first. Devices are registered

        implicitly: the first request that carries an `x-codai-device` header (a client-chosen UUID) on any

        shared-sessions or hosts endpoint inserts a row, taking the display name from `x-codai-device-name`

        (max 120 chars, default ` device`) and the platform from `x-codai-device-platform`

        (unknown values fall back to `agent`). An optional `x-codai-push-token` header on those requests upserts the

        FCM registration token. The raw push token is never echoed — `has_push_token` is all you get.

        `online` is `true` when the device was seen in the last 2 minutes.'
      parameters:
      - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: The caller's devices ordered by `lastSeenAt` descending.
          content:
            application/json:
              schema:
                type: object
                required:
                - devices
                properties:
                  devices:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeviceListItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
    servers:
    - url: https://ai.codai.ro
      description: Production
  /v1/devices/plugins:
    get:
      operationId: listDevicePlugins
      tags:
      - Devices
      summary: List the audio plugins installed on your devices
      description: The CLAP / VST3 plugins your codai desktop apps reported after their last scan, per device, most recently seen first (no file paths). Plugins the codai validator marked `failed` are left out. Used by the "on your PC" plugin pickers.
      parameters:
      - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Inventories per device.
          content:
            application/json:
              schema:
                type: object
                required:
                - devices
                properties:
                  devices:
                    type: array
                    items:
                      type: object
                      required:
                      - device_id
                      - name
                      - platform
                      - online
                      - scanned_at
                      - plugins
                      properties:
                        device_id:
                          type: string
                          format: uuid
                        name:
                          type: string
                        platform:
                          type: string
                        online:
                          type: boolean
                        scanned_at:
                          type: string
                          format: date-time
                        plugins:
                          type: array
                          items:
                            $ref: '#/components/schemas/DevicePluginItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://ai.codai.ro
      description: Production
  /v1/devices/{id}/plugins:
    put:
      operationId: putDevicePlugins
      tags:
      - Devices
      summary: Replace a device's audio plugin inventory
      description: 'Called by the codai desktop app after a plugin scan: replaces the stored inventory of one of your devices (at most 2000 plugins, de-duplicated by `format` + `id`; local paths are never sent). A device of another account is reported as 404.'
      parameters:
      - $ref: '#/components/parameters/RequestId'
      - name: id
        in: path
        required: true
        description: Device UUID (the value you send as `x-codai-device`).
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - scanned_at
              - plugins
              properties:
                scanned_at:
                  type: string
                  format: date-time
                  description: When the desktop scanned (RFC 3339 with offset).
                plugins:
                  type: array
                  maxItems: 2000
                  items:
                    $ref: '#/components/schemas/DevicePluginItem'
      responses:
        '200':
          description: Stored.
          content:
            application/json:
              schema:
                type: object
                required:
                - device_id
                - count
                - scanned_at
                properties:
                  device_id:
                    type: string
                    format: uuid
                  count:
                    type: integer
                  scanned_at:
                    type: string
                    format: date-time
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://ai.codai.ro
      description: Production
  /v1/devices/{id}:
    patch:
      operationId: updateDevice
      tags:
      - Devices
      summary: Update a device's push token or capabilities
      description: 'Updates one of your own devices. The body must contain `push_token` and/or `capabilities`; an empty object is

        a 400. Sending `push_token: null` clears the stored FCM token. `lastSeenAt` is bumped on every successful

        patch. The device name and platform cannot be changed through this endpoint (they are set at implicit

        registration). A device belonging to another account is reported as 404, never 403.'
      parameters:
      - $ref: '#/components/parameters/RequestId'
      - name: id
        in: path
        required: true
        description: Device UUID (the value you send as `x-codai-device`).
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DevicePatch'
      responses:
        '200':
          description: The updated device.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DevicePatched'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteDevice
      tags:
      - Devices
      summary: Revoke one of your devices
      description: 'Deletes the device row. Session events already sent from this device are kept (the foreign key is

        `restrict`, so a device that has ever posted an event cannot be deleted and the request fails). The device

        can re-register implicitly on its next request with the same or a new UUID. Devices of other accounts are

        reported as 404.'
      parameters:
      - $ref: '#/components/parameters/RequestId'
      - name: id
        in: path
        required: true
        description: Device UUID.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Deleted.
          content:
            application/json:
              schema:
                type: object
                required:
                - deleted
                - id
                properties:
                  deleted:
                    type: boolean
                    enum:
                    - true
                  id:
                    type: string
                    format: uuid
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://ai.codai.ro
      description: Production
  /v1/keys/self/revoke:
    post:
      operationId: revokeSelfKey
      tags:
      - Devices
      summary: Revoke the calling API key (sign out)
      description: 'The API key that authenticates this request revokes itself: it stops working at once on the instance that

        served the call and within 60 seconds everywhere (principal cache TTL). Only the calling key is affected,

        never another key of the same account. Clients call it on "Sign out" so a copied key cannot keep working.

        A key that is already revoked fails authentication with 401, which a client can treat as "already signed

        out". `revoked` is `false` only when a concurrent revoke won the race.'
      parameters:
      - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Revoked.
          content:
            application/json:
              schema:
                type: object
                required:
                - revoked
                - id
                properties:
                  revoked:
                    type: boolean
                  id:
                    type: string
                    format: uuid
                    description: Id of the revoked key.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://ai.codai.ro
      description: Production
components:
  schemas:
    SessionDispatchInbox:
      type: object
      required:
      - device_id
      - sessions
      properties:
        device_id:
          type: string
          format: uuid
          description: The calling device.
        sessions:
          type: array
          items:
            type: object
            required:
            - id
            - session_key
            - title
            - controls
            properties:
              id:
                type: string
                format: uuid
              session_key:
                type: string
              title:
                type: string
                nullable: true
              controls:
                type: array
                items:
                  $ref: '#/components/schemas/SessionControl'
    SessionControlKind:
      type: string
      enum:
      - send
      - answer
      - approve
      - deny
      - cancel
      - steer
      - inject
      - pause
      - resume
      - hydrate
      description: Kind of control a non-executor can send to the executor. `hydrate` asks the executor to upload the transcript of a stub session (session owner only, like `send`).
    DeviceListItem:
      type: object
      title: Device
      description: One registered device. Keys are camelCase for the timestamps, snake_case for `has_push_token` — exactly as the API returns them.
      required:
      - id
      - name
      - platform
      - capabilities
      - has_push_token
      - lastSeenAt
      - createdAt
      - online
      properties:
        id:
          type: string
          format: uuid
          description: Client-chosen device UUID.
          examples:
          - 2b6d8c1e-4f3a-4e9b-9c0d-7a1e5f6b8c2d
        name:
          type: string
          maxLength: 120
          description: Display name from `x-codai-device-name` at registration, or `<platform> device`.
          examples:
          - Pixel 9 Pro
        platform:
          $ref: '#/components/schemas/DevicePlatform'
        capabilities:
          type: array
          description: Free-form capability labels set via PATCH (max 64 entries, 1–64 chars each).
          items:
            type: string
            minLength: 1
            maxLength: 64
          examples:
          - - terminal
            - fs
            - voice
        has_push_token:
          type: boolean
          description: Whether an FCM registration token is stored. The token itself is never returned.
        app_version:
          type:
          - string
          - 'null'
          description: Last client version this device reported in `x-codai-client`, as `<app>/<semver>` (e.g. `desktop/0.7.0`). `null` until the device sends it.
          examples:
          - desktop/0.7.0
        lastSeenAt:
          type: string
          format: date-time
          description: Bumped on every request carrying this device id and on every PATCH.
          examples:
          - '2026-09-23T08:41:12.000Z'
        createdAt:
          type: string
          format: date-time
          examples:
          - '2026-09-01T10:00:00.000Z'
        online:
          type: boolean
          description: '`true` when `lastSeenAt` is within the last 2 minutes (any request carrying this device id bumps it). A future `lastSeenAt` (clock skew) counts as online.'
    DevicePlatform:
      type: string
      description: Client platform; anything else sent in `x-codai-device-platform` is stored as `agent`.
      enum:
      - android
      - ios
      - web
      - desktop
      - cli
      - agent
    DevicePluginItem:
      type: object
      description: An installed audio plugin as a desktop reported it.
      required:
      - format
      - id
      - name
      additionalProperties: false
      properties:
        format:
          type: string
          enum:
          - clap
          - vst3
        id:
          type: string
          pattern: ^(?:[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}|[0-9A-Fa-f]{32})$
        name:
          type: string
          minLength: 1
          maxLength: 100
        vendor:
          type: string
          maxLength: 100
        version:
          type: string
          maxLength: 40
        kind:
          type: string
          enum:
          - instrument
          - effect
          - other
        verdict:
          type: string
          enum:
          - compatible
          - limited
          - failed
          description: codai validator verdict on that machine, when it ran.
    DevicePatched:
      type: object
      title: Device (after patch)
      required:
      - id
      - name
      - platform
      - capabilities
      - has_push_token
      - lastSeenAt
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        platform:
          $ref: '#/components/schemas/DevicePlatform'
        capabilities:
          type: array
          items:
            type: string
        has_push_token:
          type: boolean
        lastSeenAt:
          type: string
          format: date-time
    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
    SessionControl:
      type: object
      title: SessionControl
      required:
      - id
      - kind
      - text
      - turn_id
      - ask_id
      - from_device_id
      - target_device_id
      - seq
      - applied
      - created_at
      properties:
        id:
          type: string
        kind:
          $ref: '#/components/schemas/SessionControlKind'
        text:
          type: string
          nullable: true
        turn_id:
          type: string
          nullable: true
        ask_id:
          type: string
          nullable: true
        from_device_id:
          type: string
          format: uuid
        target_device_id:
          type: string
          format: uuid
          nullable: true
          description: Set only for Dispatch-originated controls.
        mode:
          type: string
          enum:
          - open
          description: Present (`open`) only on a `mode:"open"` Dispatch handoff — open the session, run nothing. Absent on every other control.
        seq:
          type: integer
          nullable: true
          description: Seq of the echoed `control` event.
        applied:
          type: boolean
        created_at:
          type: string
          format: date-time
    DevicePatch:
      type: object
      title: Device patch
      description: At least one of the two fields is required.
      properties:
        push_token:
          type:
          - string
          - 'null'
          minLength: 8
          maxLength: 4096
          description: FCM registration token (opaque ASCII, trimmed). `null` clears it.
        capabilities:
          type: array
          maxItems: 64
          items:
            type: string
            minLength: 1
            maxLength: 64
          description: Replaces the whole capability list.
          examples:
          - - terminal
            - fs
  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'
  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