API Reference

OpenAPI Spec

The whole /v1 API is described in an OpenAPI 3.1 document at /v1/openapi.json: every endpoint, the key type and permissions it needs, its parameters and bodies, its responses and its error codes. Load it into Postman, Insomnia or an API client generator. It is public and needs no key. A test checks it against the route code on every change, so it lists what the API really serves.

curl -s https://headband.dev/v1/openapi.json -o headband-openapi.json

Every path also answers under /api/v1. Each operation lists the key types it takes (x-headband-key-types) and the permissions it checks (x-headband-permissions); see Authentication. Every response carries X-Request-Id; see Request IDs.

Versioning and Deprecation

/v1 is stable. Within /v1 we make additive changes only:

• new endpoints;
• new optional request fields and query parameters;
• new fields in responses;
• new error codes, and new values in fields that list kinds or states.

We do not remove or rename an endpoint or a field, change a field's type, make an optional field required, or change what an error code means, without the deprecation below. Write clients that ignore fields they do not know, and that branch on code with the HTTP status as the fallback. The error message is for people and can change at any time.

A deprecation is announced on the changelog at least 90 days before the change takes effect, and the operation is marked deprecated in the OpenAPI document. A change that cannot be made compatibly would ship as a new version, such as /v2, announced the same way.

Two exceptions. A fix for a security problem can change behavior with less notice, and we say so on the changelog. Features the docs mark as early access, such as Sync, can change faster while they are in early access; their changes are on the changelog too.