cURL

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

{
  "id": "drf_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
  "object": "draft",
  "record_id": "<string>",
  "collection_id": "<string>",
  "collection": "<string>",
  "base_revision": 123,
  "revision": 123,
  "data": {
    "title": "Introducing Foo",
    "body": {
      "type": "doc",
      "content": []
    }
  },
  "changed_fields": [
    "<string>"
  ],
  "schedule": {
    "merge_at": "2023-11-07T05:31:56Z",
    "last_error": "<string>"
  },
  "created_by": {
    "type": "user",
    "id": "<string>",
    "name": "<string>"
  },
  "edited_by": [
    {
      "type": "user",
      "id": "<string>",
      "name": "<string>"
    }
  ],
  "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": "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>"
      }
    ]
  }
}

Drafts

Start a draft

Starts the record’s draft (records:write): changes to its content that wait until they are merged, now or at a set time, while the record keeps its current values. data takes values as a record update does, validated on what the record would read after the merge. With from_revision, the draft starts from that revision’s values (mapped onto the current schema, as a revert is), to bring an earlier version back for review (400 unless it is a revision number, 404 if the record has no such revision). Works on any record, live or not.

One draft per record: a second is 409 with detail code draft_exists and its draft_id, so change that one instead. 409 with detail code deleted while the record is soft-deleted.

POST

records

{record_id}

drafts

cURL

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

{
  "id": "drf_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
  "object": "draft",
  "record_id": "<string>",
  "collection_id": "<string>",
  "collection": "<string>",
  "base_revision": 123,
  "revision": 123,
  "data": {
    "title": "Introducing Foo",
    "body": {
      "type": "doc",
      "content": []
    }
  },
  "changed_fields": [
    "<string>"
  ],
  "schedule": {
    "merge_at": "2023-11-07T05:31:56Z",
    "last_error": "<string>"
  },
  "created_by": {
    "type": "user",
    "id": "<string>",
    "name": "<string>"
  },
  "edited_by": [
    {
      "type": "user",
      "id": "<string>",
      "name": "<string>"
    }
  ],
  "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": "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

Nohead-Client

string

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

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

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": [] }
}

from_revision

integer

Start from this revision's values instead of the record's current ones.

Required range: x >= 1

Response

The started draft.

Changes to a record's content that wait until they are merged into it, now or at schedule.merge_at. Content only: whether the record is live is its publication and schedule.

string

required

Example:

"drf_01J9ZQ3F8X5W2K7M4N6P0R1S2T"

object

any

required

record_id

string

required

collection_id

string

required

collection

string

required

The collection slug.

base_revision

integer

required

The record's revision when the draft started. Fields the record changed since keep their values at the merge, unless the draft changes them too; compare with GET /v1/records/{id}/diff?from=<base_revision>.

revision

integer

required

The draft's own revision, 1 when started and one more per change; also returned as the ETag.

data

object

required

The record's values as they read after the merge.

Example:

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

changed_fields

string[]

required

Keys of the fields the draft changes.

schedule

object

required

When the draft merges on its own (within a minute of the time), set with PUT /v1/drafts/{draft_id}/schedule. last_error explains the last scheduled merge that could not be made, until a new one is set.

Show child attributes

created_by

object

required

Show child attributes

edited_by

object[]

required

Everyone who changed it since, in order.

Show child attributes

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, as on a record, for the values after the merge.

Show child attributes