Overview - Nohead

Every endpoint in this reference is generated from the API’s OpenAPI 3.1 contract, the same document the API is tested against. Download it from the API at https://api.nohead.io/openapi.json; coding agents can start from /llms.txt, a plain-text map of every endpoint.

Authentication

Requests go to https://api.nohead.io. Send Authorization: Bearer <token>. Servers, CI and agents use a project API key (nohead_sk_..., or nohead_pk_... for a published-only key; created in the web app under API keys) with scopes such as records:read (API keys). Organizations, projects, members, billing and API keys are managed in the web app, signed in, so this reference leaves them out: it covers everything an API key can call.

IDs

Every object has an object type, and every resource with an identity of its own an opaque, prefixed id (col_, fld_, rec_, ast_, …). With an API key, collections can also be addressed by slug: /v1/collections/blog-posts/records works like /v1/collections/col_…/records, since the key belongs to one project. Project endpoints take the key’s project ID (prj_…): GET /v1/me returns it as api_key.project_id, and the project’s Settings page shows it. Timestamps are ISO 8601 in UTC.

Lists

Lists return { "data": [...], "meta": { "next_cursor", "has_more" } }. Pass limit (1 to 100) and cursor to page, and sort (prefix - for descending). Reading content covers filtering, sorting and embedding records.

Errors

Errors share one envelope:

{
  "error": {
    "type": "validation_error",
    "message": "Record validation failed",
    "request_id": "req_...",
    "details": [{ "field": "title", "code": "required", "message": "is required" }]
  }
}

Include the request_id when asking for support.

Safe retries and concurrent edits

Send Idempotency-Key on any POST, PUT, PATCH or DELETE to make retrying it safe: the first result is stored for 24 hours and returned again for the same request. Record responses carry the record’s revision as an ETag; send it back as If-Match to update only if nobody changed the record in the meantime (412 otherwise).

History

Every change to a record is a revision, attributed to the person or API key that made it. Send Nohead-Change-Note to record why a change was made. A record’s history_pruned_through is the revision up to which older history was removed (null while nothing was). Revisions and history covers listing, diffing and reverting revisions, and how long they are kept.

Rate limits

Every authenticated response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. An API key’s limit depends on its organization’s plan. Over it, the API answers 429 with Retry-After, and the request is neither performed nor counted, so retrying it is safe.

Plan limits

A request that would go over a hard limit of the organization’s plan, such as its number of records or collections (or file storage, on Free), is refused with 402 plan_limit_exceeded. The error’s detail names the limit in field, with the current usage and the limit. Over a soft limit, such as file storage on paid plans, uploads still succeed and carry a Nohead-Usage-Warning header: asset_storage_bytes=53687091300/53687091200. Monthly API requests are a hard limit on Free (429 until the next month) and a soft one on paid plans: see API requests.

​Authentication

​IDs

​Lists

​Errors

​Safe retries and concurrent edits

​History

​Rate limits

​Plan limits