> ## 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. # Update a draft > Changes the draft's values (`records:write`), as a record update does: keys present in `data` replace their values, and `null` clears one. A value set back to the record's drops out of the draft. ## OpenAPI ````yaml /openapi.json patch /v1/drafts/{draft_id} openapi: 3.1.1 info: title: Nohead API version: 1.0.0 summary: Programmable content and data API. contact: name: Nohead email: hello@nohead.io url: https://nohead.io description: > The Nohead API manages projects, collections (your data models), their fields, and records (your content), with full version history. ## Authentication Send `Authorization: Bearer `. 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` or `schema:write`. Organization, project, member and API key management need a person signed in to the web app and are not available to API keys. ## Resources and IDs Every object has an `object` type, and every resource with an identity of its own an opaque, prefixed `id` (`col_`, `fld_`, `rec_`, ...). Record values live under `data`, keyed by each field's `key`. Timestamps are ISO 8601 in UTC. Deleting a record, collection, field, asset or webhook is soft: it can be restored until its `purge_after`. ## Lists Lists return `{ "data": [...], "meta": { "next_cursor", "has_more" } }`. Pass `limit` (1-100) and `cursor` to page, and `sort` (prefix `-` for descending). Records also take `filter[]=value`, `filter[published_at][exists]=true` and `expand=`. ## Errors Errors share one envelope: `{ "error": { "type", "message", "request_id", "details" } }`. `details` lists field-level problems as `{ "field", "code", "message" }`. 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: record revisions can be listed, diffed and reverted, and collections keep a schema history. Send `Nohead-Change-Note` to record why a change was made. Changes that rewrite existing values (such as a field's type) are explicit, previewable field migrations. How long revisions are kept depends on the organization's plan. Older ones are removed, but every record keeps its first revision and its last 10; `history_pruned_through` says how far history was removed. license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.nohead.io description: Production security: - apiKey: [] tags: - name: records x-group: Records description: Content entries, one at a time or many at once. - name: publishing x-group: Publishing description: Making records live, now or at a set time, and taking them down. - name: revisions x-group: Revisions description: A record's history, comparing two revisions, and going back to one. - name: drafts x-group: Drafts description: Changes to a record that wait to be merged into it, now or at a set time. - name: collections x-group: Collections description: User-defined data models. - name: schema-changes x-group: Schema changes description: A collection's schema history, and its schema at any version. - name: fields x-group: Fields description: Field definitions of a collection. - name: migrations x-group: Field migrations description: Explicit field changes that rewrite existing record values, with previews. - name: assets x-group: Assets description: Files stored for a project, uploaded directly to storage. - name: search x-group: Search description: Full-text search in collections and across a project. - name: webhooks x-group: Webhooks description: Event notifications sent to your URLs, and the secrets that sign them. - name: deliveries x-group: Webhook deliveries description: Each event sent to a webhook, its attempts, and retrying it. - name: audit x-group: Activity log description: The append-only trail of who changed what, through which client. - name: system x-group: System description: Service status, the caller, and its feature flags. paths: /v1/drafts/{draft_id}: parameters: - $ref: '#/components/parameters/DraftId' patch: tags: - drafts summary: Update a draft description: | Changes the draft's values (`records:write`), as a record update does: keys present in `data` replace their values, and `null` clears one. A value set back to the record's drops out of the draft. operationId: drafts_update parameters: - $ref: '#/components/parameters/RichText' - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/IfMatch' - $ref: '#/components/parameters/NoheadClient' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RecordWrite' responses: '200': $ref: '#/components/responses/Draft' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '412': $ref: '#/components/responses/PreconditionFailed' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' x-codeSamples: - lang: typescript label: TypeScript source: | import { Nohead } from "@nohead/sdk" const nohead = new Nohead() const result = await nohead.drafts.update( "drf_01J9ZQ3F8X", { data: { title: "Hey there" } }, { ifMatch: 1 } ) - lang: python label: Python source: > from nohead import Nohead nohead = Nohead() result = nohead.drafts.update("drf_01J9ZQ3F8X", data={"title": "Hey there"}, if_match=1) - lang: ruby label: Ruby source: > require "nohead" nohead = Nohead::Client.new result = nohead.drafts.update("drf_01J9ZQ3F8X", data: { title: "Hey there" }, if_match: 1) components: parameters: DraftId: name: draft_id in: path required: true schema: type: string example: drf_01J9ZQ3F8X5W2K7M4N6P0R1S2T RichText: name: rich_text in: query description: >- 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. schema: type: string enum: - document - html - markdown default: document IdempotencyKey: name: Idempotency-Key in: header required: false description: | 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`. schema: type: string minLength: 1 maxLength: 255 example: 8f14e45f-ceea-467a-9575-0f1a3f2c1d2e IfMatch: name: If-Match in: header description: >- The revision you last read (the record's, or the draft's for a draft), e.g. `"7"`. Stale writes fail with 412. schema: type: string NoheadClient: name: Nohead-Client in: header description: >- First-party client identifier recorded in history (e.g. `cli/0.3.1`). Informational only. schema: type: string schemas: RecordWrite: type: object additionalProperties: false required: - data properties: data: $ref: '#/components/schemas/RecordData' RecordData: type: object description: > 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. additionalProperties: true examples: - title: Introducing Foo body: type: doc content: [] Draft: type: object additionalProperties: false required: - id - object - record_id - collection_id - collection - base_revision - revision - data - changed_fields - schedule - created_by - edited_by - created_at - updated_at description: | 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. properties: id: type: string examples: - drf_01J9ZQ3F8X5W2K7M4N6P0R1S2T object: const: draft record_id: type: string collection_id: type: string collection: type: string description: The collection slug. base_revision: type: integer description: > 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=`. revision: type: integer description: >- The draft's own revision, 1 when started and one more per change; also returned as the ETag. data: $ref: '#/components/schemas/RecordData' description: The record's values as they read after the merge. changed_fields: type: array description: Keys of the fields the draft changes. items: type: string schedule: $ref: '#/components/schemas/DraftSchedule' created_by: $ref: '#/components/schemas/Actor' edited_by: type: array description: Everyone who changed it since, in order. items: $ref: '#/components/schemas/Actor' expanded: type: object description: Only with `expand`, as on a record, for the values after the merge. additionalProperties: anyOf: - $ref: '#/components/schemas/Record' - $ref: '#/components/schemas/Asset' - type: 'null' - type: array items: anyOf: - $ref: '#/components/schemas/Record' - $ref: '#/components/schemas/Asset' created_at: $ref: '#/components/schemas/Timestamp' updated_at: $ref: '#/components/schemas/Timestamp' Error: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - type - message - request_id properties: type: $ref: '#/components/schemas/ErrorType' message: type: string request_id: $ref: '#/components/schemas/RequestId' details: type: array items: $ref: '#/components/schemas/ErrorDetail' DraftSchedule: type: object additionalProperties: false required: - merge_at - last_error description: | 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. properties: merge_at: $ref: '#/components/schemas/NullableTimestamp' last_error: type: - string - 'null' Actor: type: object additionalProperties: false required: - type - id - name properties: type: type: string enum: - user - api_key - system id: type: - string - 'null' description: >- The user (`usr_...`) or API key (`key_...`), or null for system changes. name: type: - string - 'null' description: | Resolved when read, never stored: a user's current name (or email), "Deleted user" once they deleted their account, an API key's name, or "System". Record: type: object additionalProperties: false required: - id - object - collection_id - collection - published_at - revision - schema_version - deleted_at - purge_after - history_pruned_through - data - created_at - updated_at properties: id: type: string examples: - rec_01J9ZQ3F8X5W2K7M4N6P0R1S2T object: const: record collection_id: type: string collection: type: string description: The collection slug. published_at: $ref: '#/components/schemas/NullableTimestamp' description: When the record was published; null while it is unpublished. revision: type: integer description: Current revision number; also returned as the ETag. schema_version: type: integer history_pruned_through: type: - integer - 'null' description: >- Revisions up to this number (except revision 1) were removed by the plan's history retention. deleted_at: $ref: '#/components/schemas/NullableTimestamp' description: When the record was soft-deleted; null unless it is. purge_after: $ref: '#/components/schemas/NullableTimestamp' description: >- When a soft-deleted record is removed for good, unless restored first. data: $ref: '#/components/schemas/RecordData' expanded: type: object description: > 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. additionalProperties: anyOf: - $ref: '#/components/schemas/Record' - $ref: '#/components/schemas/Asset' - type: 'null' - type: array items: anyOf: - $ref: '#/components/schemas/Record' - $ref: '#/components/schemas/Asset' created_at: $ref: '#/components/schemas/Timestamp' updated_at: $ref: '#/components/schemas/Timestamp' Asset: allOf: - $ref: '#/components/schemas/AssetProperties' unevaluatedProperties: false Timestamp: type: string format: date-time description: ISO 8601 timestamp in UTC. examples: - '2026-09-27T12:00:00.000Z' RequestId: type: string pattern: ^req_[A-Za-z0-9]+$ examples: - req_01J9ZQ3F8X5W2K7M4N6P0R1S2T ErrorType: type: string enum: - invalid_request - authentication_error - plan_limit_exceeded - authorization_error - not_found - conflict - precondition_failed - validation_error - rate_limited - internal_error - service_unavailable ErrorDetail: type: object additionalProperties: false required: - code - message properties: field: type: string description: Key of the offending field or parameter, when applicable. code: type: string description: Machine-readable error code, e.g. `required`. message: type: string usage: type: integer description: Current usage, for `plan_limit` details. limit: type: integer description: The plan's limit, for `plan_limit` details. current_revision: type: integer description: The resource's current revision, for `revision_mismatch` details. record_id: type: string description: The record that already has the value, for `taken` details. draft_id: type: string description: The record's draft, for `draft_exists` and `draft_pending` details. NullableTimestamp: type: - string - 'null' format: date-time AssetProperties: type: object required: - id - object - project_id - filename - alt - content_type - byte_size - width - height - status - deleted_at - purge_after - image_url - preview_url - file_url - media_url - uploaded_at - created_at - updated_at properties: id: type: string examples: - ast_01J9ZQ3F8X5W2K7M4N6P0R1S2T object: const: asset project_id: type: string filename: type: string description: >- The filename, any Unicode, as uploaded unless renamed since. Downloads use it. alt: type: - string - 'null' maxLength: 1000 description: >- Alternative text, saying what an image shows; null until set. The default wherever the asset is used. content_type: type: string examples: - image/png byte_size: type: integer width: type: - integer - 'null' description: Pixel width, for images. height: type: - integer - 'null' status: type: string enum: - pending - ready - failed description: >- `pending` until the upload is completed; only `ready` assets can be used in records. deleted_at: $ref: '#/components/schemas/NullableTimestamp' description: When the asset was deleted; null unless it is. purge_after: $ref: '#/components/schemas/NullableTimestamp' description: >- When a deleted asset and its file are removed for good, unless restored or purged first. image_url: type: - string - 'null' format: uri description: > The URL of the whole image, for ready images (JPEG, PNG, GIF, WebP, AVIF or SVG), deleted ones included until they are purged; null otherwise. Image URLs are open and never expire. An SVG is served as SVG without its scripts, unless a format such as `@webp` rasterizes it. For a rendition, write [imgproxy processing options](https://docs.imgproxy.net/usage/processing) before `/plain/`, and a format after `@`: for example `https://images.nohead.io/rs:fill:800:600/g:sm/plain/…@webp`. Renditions are at most 4096 pixels a side, from originals of at most 50 megapixels. Options that would return the file as stored (`raw`, `skip_processing`, `strip_metadata`) are refused. examples: - >- https://images.nohead.io/plain/0199f5c2-7b1e-7c3a-9d4f-2a6b8c0e1f3d/0199f5c2-8a2d-7e4b-b1c3-5d7e9f1a2b4c preview_url: type: - string - 'null' format: uri description: >- The URL of a small rendition (fits in 640×640, WebP), for ready images and SVGs (rasterized), deleted ones included until they are purged; null otherwise. file_url: type: - string - 'null' format: uri description: | The URL of the file as uploaded, for ready assets of any type, deleted ones included until they are purged; null otherwise. It downloads the file under its `filename` (a rename applies within a minute or so), is open and never expires, and is cached on a CDN. examples: - >- https://files.nohead.io/0199f5c2-7b1e-7c3a-9d4f-2a6b8c0e1f3d/0199f5c2-8a2d-7e4b-b1c3-5d7e9f1a2b4c media_url: type: - string - 'null' format: uri description: | The URL that plays a ready video or audio file inline, for `