# Nohead API

> A headless content platform: collections with typed fields, records with full version history, assets with image transformations, search and signed webhooks, over one REST API.

Authenticate with `Authorization: Bearer <API key>`; keys (`nohead_sk_...`, or `nohead_pk_...` when published-only) are scoped to one project and a set of scopes such as `records:read`. Every endpoint, schema and error is in the OpenAPI contract below.

- [OpenAPI contract](/openapi.json): the complete machine-readable reference (OpenAPI 3.1)
- [Docs](https://docs.nohead.io): guides, and the same reference rendered for people
- [MCP server](https://mcp.nohead.io/mcp): the same API as tools, for agents without a shell (Streamable HTTP, the same API key)

## Conventions

- Errors: `{ "error": { "type", "message", "request_id", "details": [{ "field", "code", "message" }] } }`
- Lists: cursor pagination with `limit` (max 100) and `cursor`; read `meta.next_cursor` and `meta.has_more`
- Retries: send an `Idempotency-Key` header on writes; the same key and request return the first result for 24 hours
- Records: `ETag` is the revision; send `If-Match: "<revision>"` to avoid overwriting newer changes
- Attribution: `Nohead-Client` names your tool and `Nohead-Change-Note` explains a change (percent-encoded UTF-8, as `encodeURIComponent` encodes it); both appear in history
- IDs are prefixed (`col_`, `rec_`, `fld_`, `ast_`); collections may also be addressed by slug with an API key

## Records

Content entries, one at a time or many at once.

- `GET /v1/collections/{collection_id}/records`: List records
- `POST /v1/collections/{collection_id}/records`: Create a record
- `GET /v1/records/{record_id}`: Get a record
- `PATCH /v1/records/{record_id}`: Update a record
- `DELETE /v1/records/{record_id}`: Delete a record
- `GET /v1/collections/{collection_id}/records/count`: Count records
- `POST /v1/collections/{collection_id}/record-batches`: Change many records
- `POST /v1/records/{record_id}/restore`: Restore a record

## Publishing

Making records live, now or at a set time, and taking them down.

- `GET /v1/records/{record_id}/publication`: Get a record's publication
- `POST /v1/records/{record_id}/publication`: Publish a record
- `DELETE /v1/records/{record_id}/publication`: Unpublish a record
- `GET /v1/records/{record_id}/schedule`: Get a record's schedule
- `PUT /v1/records/{record_id}/schedule`: Schedule publishing or unpublishing
- `DELETE /v1/records/{record_id}/schedule`: Cancel a record's schedule
- `GET /v1/collections/{collection_id}/scheduled-changes`: List scheduled changes

## Revisions

A record's history, comparing two revisions, and going back to one.

- `GET /v1/records/{record_id}/revisions`: List a record's revisions
- `GET /v1/records/{record_id}/revisions/{revision}`: Get a revision
- `GET /v1/revisions/{revision_id}`: Get a revision by ID
- `POST /v1/records/{record_id}/revisions/{revision}/revert`: Revert to a revision
- `GET /v1/records/{record_id}/diff`: Compare two revisions

## Drafts

Changes to a record that wait to be merged into it, now or at a set time.

- `GET /v1/records/{record_id}/drafts`: List a record's drafts
- `POST /v1/records/{record_id}/drafts`: Start a draft
- `GET /v1/collections/{collection_id}/drafts`: List drafts
- `GET /v1/drafts/{draft_id}`: Get a draft
- `PATCH /v1/drafts/{draft_id}`: Update a draft
- `DELETE /v1/drafts/{draft_id}`: Discard a draft
- `POST /v1/drafts/{draft_id}/merge`: Merge a draft
- `PUT /v1/drafts/{draft_id}/schedule`: Schedule a draft's merge
- `DELETE /v1/drafts/{draft_id}/schedule`: Cancel a draft's merge

## Collections

User-defined data models.

- `GET /v1/projects/{project_id}/collections`: List collections
- `POST /v1/projects/{project_id}/collections`: Create a collection
- `GET /v1/collections/{collection_id}`: Get a collection
- `PATCH /v1/collections/{collection_id}`: Update a collection
- `DELETE /v1/collections/{collection_id}`: Delete a collection
- `POST /v1/collections/{collection_id}/restore`: Restore a deleted collection

## Schema changes

A collection's schema history, and its schema at any version.

- `GET /v1/collections/{collection_id}/schema`: Get the schema at a version
- `GET /v1/collections/{collection_id}/schema-changes`: List schema changes
- `GET /v1/schema-changes/{schema_change_id}`: Get a schema change

## Fields

Field definitions of a collection.

- `GET /v1/collections/{collection_id}/fields`: List fields
- `POST /v1/collections/{collection_id}/fields`: Add a field
- `GET /v1/fields/{field_id}`: Get a field
- `PATCH /v1/fields/{field_id}`: Update a field
- `DELETE /v1/fields/{field_id}`: Delete a field
- `GET /v1/collections/{collection_id}/field-order`: Get the field order
- `PUT /v1/collections/{collection_id}/field-order`: Reorder fields
- `DELETE /v1/fields/{field_id}/aliases/{alias}`: Stop accepting a renamed field's old key
- `POST /v1/fields/{field_id}/restore`: Restore a deleted field

## Field migrations

Explicit field changes that rewrite existing record values, with previews.

- `GET /v1/collections/{collection_id}/migrations`: List field migrations
- `POST /v1/collections/{collection_id}/migrations`: Migrate a field
- `GET /v1/migrations/{migration_id}`: Get a field migration
- `POST /v1/migrations/{migration_id}/cancel`: Cancel a field migration

## Assets

Files stored for a project, uploaded directly to storage.

- `GET /v1/projects/{project_id}/assets`: List assets
- `POST /v1/projects/{project_id}/assets`: Start an upload
- `POST /v1/assets/{asset_id}/complete`: Complete an upload
- `GET /v1/assets/{asset_id}`: Get an asset
- `PATCH /v1/assets/{asset_id}`: Update an asset
- `DELETE /v1/assets/{asset_id}`: Delete an asset
- `GET /v1/assets/{asset_id}/usage`: See where an asset is used
- `POST /v1/assets/{asset_id}/restore`: Restore a deleted asset
- `POST /v1/assets/{asset_id}/purge`: Permanently delete a deleted asset

## Search

Full-text search in collections and across a project.

- `GET /v1/collections/{collection_id}/search`: Search records
- `GET /v1/projects/{project_id}/search`: Search across collections
- `GET /v1/collections/{collection_id}/search-index`: Get search index status
- `POST /v1/collections/{collection_id}/search-index/rebuild`: Rebuild the search index

## Webhooks

Event notifications sent to your URLs, and the secrets that sign them.

- `GET /v1/projects/{project_id}/webhooks`: List webhooks
- `POST /v1/projects/{project_id}/webhooks`: Create a webhook
- `GET /v1/webhooks/{webhook_id}`: Get a webhook
- `PATCH /v1/webhooks/{webhook_id}`: Update a webhook
- `DELETE /v1/webhooks/{webhook_id}`: Delete a webhook
- `POST /v1/webhooks/{webhook_id}/test`: Send a test event
- `GET /v1/webhooks/{webhook_id}/secrets`: List a webhook's secrets
- `POST /v1/webhooks/{webhook_id}/secrets`: Rotate a webhook's signing secret
- `DELETE /v1/webhook-secrets/{secret_id}`: Retire a webhook secret
- `POST /v1/webhooks/{webhook_id}/restore`: Restore a webhook

## Webhook deliveries

Each event sent to a webhook, its attempts, and retrying it.

- `GET /v1/webhooks/{webhook_id}/deliveries`: List deliveries
- `GET /v1/webhook-deliveries/{delivery_id}`: Get a delivery
- `POST /v1/webhook-deliveries/{delivery_id}/retry`: Retry a delivery

## Activity log

The append-only trail of who changed what, through which client.

- `GET /v1/projects/{project_id}/audit-events`: List a project's audit events

## System

Service status, the caller, and its feature flags.

- `GET /v1/health`: Check API health
- `GET /v1/me`: Get the authenticated principal
- `GET /v1/feature-flags`: Get evaluated feature flags