Update a record

cURL

curl --request PATCH \
  --url https://api.nohead.io/v1/records/{record_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "data": {
    "title": "Introducing Foo",
    "body": {
      "type": "doc",
      "content": []
    }
  }
}
'

{
  "id": "rec_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
  "object": "record",
  "collection_id": "<string>",
  "collection": "<string>",
  "published_at": "2023-11-07T05:31:56Z",
  "revision": 123,
  "schema_version": 123,
  "history_pruned_through": 123,
  "deleted_at": "2023-11-07T05:31:56Z",
  "purge_after": "2023-11-07T05:31:56Z",
  "data": {
    "title": "Introducing Foo",
    "body": {
      "type": "doc",
      "content": []
    }
  },
  "created_at": "2026-09-27T12:00:00.000Z",
  "updated_at": "2026-09-27T12:00:00.000Z",
  "expanded": {}
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "precondition_failed",
    "message": "Record has changed since revision 6",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "revision_mismatch",
        "message": "Current revision is 7",
        "current_revision": 7
      }
    ]
  }
}

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

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

PATCH

records

{record_id}

cURL

curl --request PATCH \
  --url https://api.nohead.io/v1/records/{record_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "data": {
    "title": "Introducing Foo",
    "body": {
      "type": "doc",
      "content": []
    }
  }
}
'

{
  "id": "rec_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
  "object": "record",
  "collection_id": "<string>",
  "collection": "<string>",
  "published_at": "2023-11-07T05:31:56Z",
  "revision": 123,
  "schema_version": 123,
  "history_pruned_through": 123,
  "deleted_at": "2023-11-07T05:31:56Z",
  "purge_after": "2023-11-07T05:31:56Z",
  "data": {
    "title": "Introducing Foo",
    "body": {
      "type": "doc",
      "content": []
    }
  },
  "created_at": "2026-09-27T12:00:00.000Z",
  "updated_at": "2026-09-27T12:00:00.000Z",
  "expanded": {}
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "precondition_failed",
    "message": "Record has changed since revision 6",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "revision_mismatch",
        "message": "Current revision is 7",
        "current_revision": 7
      }
    ]
  }
}

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

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Project-scoped API key, e.g. nohead_sk_k7fz0a9c3m2q_<secret>, or nohead_pk_… for a published-only key. Used by servers, CI, the CLI and coding agents.

Headers

Idempotency-Key

string

A unique value (1-255 printable ASCII characters) that makes retrying this request safe. The first response (below 500) is stored for 24 hours per user or API key; retries with the same key and the same request get it again with an Idempotent-Replayed: true header. The same key with a different request is refused with 400; a retry while the first request is still running gets 409.

Required string length: 1 - 255

If-Match

string

The revision you last read (the record's, or the draft's for a draft), e.g. "7". Stale writes fail with 412.

Nohead-Client

string

First-party client identifier recorded in history (e.g. cli/0.3.1). Informational only.

Nohead-Change-Note

string

Optional reason for the change, kept with the record revision, schema change or field migration it makes (at most 500 characters once decoded). Percent-encoded UTF-8, as encodeURIComponent encodes it, so any language fits in a header: Rettet%20stavefejl%20p%C3%A5%20forsiden. Plain ASCII may be sent as is. Other bytes are 400.

Path Parameters

record_id

string

required

Query Parameters

rich_text

enum<string>

default:document

How rich text fields read in the records and drafts returned (and in records they embed with expand): document, the stored ProseMirror JSON document; html, an HTML fragment of known elements with every text and attribute escaped, to put in a page as it is; or markdown (GitHub Flavored), which reads back as the same document when written. Images render with their URLs, so they need no expand: in HTML a WebP rendition at most 1600 pixels wide with its width and height (an SVG as itself), in Markdown the asset's image_url. An image whose asset was deleted is left out of HTML, and written as its asset ID in Markdown. Record history keeps documents.

Available options:

document,

html,

markdown

Body

application/json

data

object

required

Field values keyed by field key.

A rich text value is written as Markdown (GitHub Flavored, a string) or as a ProseMirror JSON document ({"type": "doc", "content": [...]}), and stored and read as the document (rich_text reads it as HTML or Markdown). Markdown is converted as closely as the vocabulary allows: headings below h3 become h3, task list items plain items, footnotes and raw HTML text. A document uses the web editor's vocabulary (Tiptap's StarterKit and tables) and nothing else; another name is refused with invalid_format, naming ours where one fits (strong is bold):

blocks: paragraph, heading (level 1-3), blockquote, bulletList and orderedList (start, type) of listItem (starting with a paragraph), codeBlock (language), horizontalRule, and table of tableRow of tableHeader or tableCell (colspan, rowspan, colwidth, align); any block may have dir (auto, ltr, rtl);
inline: text (non-empty) and hardBreak;
marks on text: bold, italic, strike, underline, code (alone), and link (href, and target, rel, class, title); a link's href is an http, https, mailto, tel or relative URL.

An image of an asset is {"type": "image", "attrs": {"asset_id": "ast_...", "alt": "..."}} (in Markdown ![alt](ast_...), or the asset's image_url), between the document's blocks (not inside a list, quote or table), at most 100 per document (too_many_images); a newly shown image must be an uploaded JPEG, PNG, GIF, WebP, AVIF or SVG of the project (invalid_reference, type_not_accepted). expand embeds the assets, and published-only keys can read the images of published records. A record holds at most 2,000,000 bytes of values, all fields together (too_large on data); one already larger can still be edited without growing.

Example:

{
  "title": "Introducing Foo",
  "body": { "type": "doc", "content": [] }
}

Response

The record.

string

required

Example:

"rec_01J9ZQ3F8X5W2K7M4N6P0R1S2T"

object

any

required

collection_id

string

required

collection

string

required

The collection slug.

published_at

string<date-time> | null

required

When the record was published; null while it is unpublished.

revision

integer

required

Current revision number; also returned as the ETag.

schema_version

integer

required

history_pruned_through

integer | null

required

Revisions up to this number (except revision 1) were removed by the plan's history retention.

deleted_at

string<date-time> | null

required

When the record was soft-deleted; null unless it is.

purge_after

string<date-time> | null

required

When a soft-deleted record is removed for good, unless restored first.

data

object

required

Field values keyed by field key.

blocks: paragraph, heading (level 1-3), blockquote, bulletList and orderedList (start, type) of listItem (starting with a paragraph), codeBlock (language), horizontalRule, and table of tableRow of tableHeader or tableCell (colspan, rowspan, colwidth, align); any block may have dir (auto, ltr, rtl);
inline: text (non-empty) and hardBreak;
marks on text: bold, italic, strike, underline, code (alone), and link (href, and target, rel, class, title); a link's href is an http, https, mailto, tel or relative URL.

Example:

{
  "title": "Introducing Foo",
  "body": { "type": "doc", "content": [] }
}

created_at

string<date-time>

required

ISO 8601 timestamp in UTC.

Example:

"2026-09-27T12:00:00.000Z"

updated_at

string<date-time>

required

ISO 8601 timestamp in UTC.

Example:

"2026-09-27T12:00:00.000Z"

expanded

object

Only with expand: what each requested relation, asset or rich text field points at, keyed by field key: records for relation fields, assets for asset fields. A single value is the object, or null when it no longer exists; a multiple value is a list of those that still exist. For a rich text field, the list of assets its images show, in document order, leaving out those that no longer exist. Expanded records are not expanded further.

Show child attributes