Lab

REST API

Read the components, their docs and the catalog as JSON from https://www.audio-ui.dev/api/v1: public, read-only and versioned.

The REST API gives programs and agents what the docs say, as JSON: the components, their docs as markdown, a search of the docs and the catalog of ready-made blocks. It answers the same questions as the MCP server, for any client that speaks HTTP.

https://www.audio-ui.dev/api/v1

It is public and read-only: no key, no account. Answers can be read from any origin and are cached for five minutes. The whole API is described in OpenAPI 3.1 at /openapi.json, and listed at /.well-known/api-catalog.

Endpoints

Endpoints · 5

GET /api/v1
The entry point: the version and where every endpoint is.
GET /api/v1/components
Every component. kind keeps one kind: elements, workstation or devices.
GET /api/v1/components/{name}
One component and its docs as markdown. section returns one part, such as installation or api-reference.
GET /api/v1/search
The parts of the docs that answer q, best first, limit of them (8 by default, 20 at most).
GET /api/v1/catalog
The ready-made blocks and demos, 25 at a time. q searches them, offset turns the page.

Find a component, then read the part of its docs you need:

curl "https://www.audio-ui.dev/api/v1/search?q=log+scale+knob"
curl "https://www.audio-ui.dev/api/v1/components/knob?section=api-reference"

Every component carries the command that installs it, such as npx shadcn@latest add @audio-ui/knob.

Errors

Every error is JSON, whatever the request accepts, with the status, a stable code, what went wrong and what to do next:

{
  "error": "not_found",
  "message": "There is no component named \"knobb\".",
  "hint": "Did you mean knob? List the components at https://www.audio-ui.dev/api/v1/components, or search them at https://www.audio-ui.dev/api/v1/search?q=.",
  "status": 404
}

Error codes · 4

invalid_parameter
400: a query parameter is missing or out of range. The message names it.
not_found
404: no component of that name, or no endpoint at that address.
method_not_allowed
405: the API only reads. Send a GET or a HEAD.
rate_limited
429: too many requests from one address. Wait for Retry-After.

Rate limits

Each address may send 120 requests a minute, counted in each Cloudflare location. Every answer states the quota in a RateLimit-Policy header, from the IETF RateLimit header fields:

RateLimit-Policy: "api";q=120;w=60

Past it, the API answers 429 with a RateLimit header that says nothing is left in the window, and a Retry-After header in seconds. Wait that long, then go on at a slower pace:

HTTP/1.1 429 Too Many Requests
RateLimit: "api";r=0;t=60
Retry-After: 60

Versioning and deprecation

The version is in the path: /api/v1. Within a version, changes only add: new endpoints, new optional parameters, new fields in the answers. Ignore the fields you do not know. A change that could break a client, such as removing or renaming an endpoint, a parameter or a field, ships as a new version, /api/v2, and /api/v1 keeps answering beside it.

An endpoint is deprecated at least six months before it is removed. From that day:

  • Its answers carry a Deprecation header (RFC 9745) with the date it was deprecated, and a Sunset header (RFC 8594) with the date after which it may stop answering.
  • Its entry in /openapi.json is marked deprecated.
  • This page says what replaces it.

Nothing is deprecated today. /api lists the versions and their status.

The registry, the markdown docs, llms.txt and the MCP server are not part of this API: they follow their own formats, the shadcn registry schema, llmstxt.org and the MCP protocol version.

MCPllms.txt
Built by Ouest Labs, the source code is available on GitHub.
RSS