For tool builders

API reference

A free, read-only REST API over the OpenDeviceIO registry. No key, no auth, CORS-enabled — call it from a browser plugin or a backend. For how to map the data into your tool, see the implementation guide.

Overview

• Base URL: https://opendeviceio.org/api/v1
• Auth: none.
• Methods: GET and OPTIONS only.
• Format: JSON (application/json).

get /api/v1/devices

List and search the registry. All parameters are optional.

Returns { data, total, limit, offset }, where data is an array of list rows (the document metadata, without the heavy document body) and total is the unpaginated match count.

curl

shell
curl "https://opendeviceio.org/api/v1/devices?q=lightware&kind=device&limit=20"

fetch

typescript
const url = new URL("https://opendeviceio.org/api/v1/devices");
url.searchParams.set("q", "lightware");
url.searchParams.set("kind", "device");
url.searchParams.set("limit", "20");
url.searchParams.set("offset", "0");

const res = await fetch(url);
const { data, total, limit, offset } = await res.json();

Example response

json
{
  "data": [
    {
      "id": "lightware/ucx-4x2-hc60d",
      "kind": "device",
      "manufacturer": "Lightware",
      "model": "UCX-4x2-HC60D",
      "category": "matrix-switcher",
      "product_line": "Taurus",
      "sku": "91840012",
      "validation_status": "reviewed",
      "odio_version": "0.1.0",
      "port_count": 12,
      "connectors": ["hdmi-type-a", "usb-c", "rj45"],
      "transports": ["hdmi", "usb", "ethernet"],
      "created_at": "2026-01-10T00:00:00.000Z",
      "updated_at": "2026-01-10T00:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

get /api/v1/devices/{id}

Fetch the full ODIO document for one entry. The id is a catch-all path segment, so it carries the slash inside an id verbatim — e.g. /api/v1/devices/lightware/ucx-4x2-hc60d. Returns the raw .odio document (device, bundle, or cable). A missing id returns 404 with { "error": "not found" }.

curl

shell
curl "https://opendeviceio.org/api/v1/devices/lightware/ucx-4x2-hc60d"

fetch

typescript
// ids contain slashes — don't URL-encode the slashes between segments.
const id = "lightware/ucx-4x2-hc60d";
const res = await fetch(`https://opendeviceio.org/api/v1/devices/${id}`);
if (res.status === 404) {
  // unknown id
} else {
  const document = await res.json(); // the full .odio document
}

Example response (200)

json
{
  "$schema": "https://opendeviceio.org/schema/v0.1/device.schema.json",
  "odioVersion": "0.1.0",
  "id": "lightware/ucx-4x2-hc60d",
  "device": { "manufacturer": "Lightware", "model": "UCX-4x2-HC60D" },
  "ports": [
    {
      "id": "hdmi-in-1",
      "label": "HDMI INPUT 1",
      "direction": "input",
      "connector": "hdmi-type-a",
      "link": { "type": "hdmi", "standard": "hdmi-2.0", "bandwidthGbps": 18 },
      "signals": [
        { "domain": "video", "transport": "hdmi", "maxResolution": "4096x2160" },
        { "domain": "audio", "transport": "lpcm", "maxChannelsPerCircuit": 8 }
      ]
    }
  ]
}

Not found (404)

json
{ "error": "not found" }

CORS

Both endpoints send Access-Control-Allow-Origin: * and Access-Control-Allow-Methods: GET, OPTIONS, and answer CORS preflight (OPTIONS) requests. You can call the API directly from browser-based tools and plugins without a proxy.

Usage & limits

The API is free and read-only — there is no write endpoint and no API key. Please cache responses where reasonable rather than re-fetching on every render; documents change infrequently. Responses are served fresh (Cache-Control: no-store) so you always get current data.

Want strong typing on the client? Validate responses with @opendeviceio/sdk — see the implementation guide.