> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nohead.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> How every endpoint authenticates, pages, fails and retries.

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](https://docs.nohead.io/guides/api-keys.md)). 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](https://docs.nohead.io/guides/reading-content.md) covers filtering, sorting and embedding records.

## Errors

Errors share one envelope:

```json theme={null}
{
  "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](https://docs.nohead.io/guides/history.md) 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](https://docs.nohead.io/guides/api-requests.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.