Add a field - Nohead

cURL

curl --request POST \
  --url https://api.nohead.io/v1/collections/{collection_id}/fields \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "key": "<string>",
  "type": "text",
  "required": true,
  "multiple": true,
  "configuration": {
    "description": "<string>",
    "searchable": true,
    "filterable": true,
    "sortable": true,
    "min_length": 1,
    "max_length": 1,
    "unique": true
  }
}
'

{
  "id": "fld_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
  "object": "field",
  "collection_id": "<string>",
  "name": "<string>",
  "key": "<string>",
  "required": true,
  "multiple": true,
  "position": 123,
  "deleted_at": "2023-11-07T05:31:56Z",
  "purge_after": "2023-11-07T05:31:56Z",
  "aliases": [
    {
      "key": "<string>",
      "expires_at": "2026-09-27T12:00:00.000Z"
    }
  ],
  "created_at": "2026-09-27T12:00:00.000Z",
  "updated_at": "2026-09-27T12:00:00.000Z",
  "type": "text",
  "configuration": {
    "description": "<string>",
    "searchable": true,
    "filterable": true,
    "sortable": true,
    "min_length": 1,
    "max_length": 1,
    "format": "slug",
    "unique": true
  }
}

{
  "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>"
      }
    ]
  }
}

POST

collections

{collection_id}

fields

cURL

curl --request POST \
  --url https://api.nohead.io/v1/collections/{collection_id}/fields \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "key": "<string>",
  "type": "text",
  "required": true,
  "multiple": true,
  "configuration": {
    "description": "<string>",
    "searchable": true,
    "filterable": true,
    "sortable": true,
    "min_length": 1,
    "max_length": 1,
    "unique": true
  }
}
'

{
  "id": "fld_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
  "object": "field",
  "collection_id": "<string>",
  "name": "<string>",
  "key": "<string>",
  "required": true,
  "multiple": true,
  "position": 123,
  "deleted_at": "2023-11-07T05:31:56Z",
  "purge_after": "2023-11-07T05:31:56Z",
  "aliases": [
    {
      "key": "<string>",
      "expires_at": "2026-09-27T12:00:00.000Z"
    }
  ],
  "created_at": "2026-09-27T12:00:00.000Z",
  "updated_at": "2026-09-27T12:00:00.000Z",
  "type": "text",
  "configuration": {
    "description": "<string>",
    "searchable": true,
    "filterable": true,
    "sortable": true,
    "min_length": 1,
    "max_length": 1,
    "format": "slug",
    "unique": true
  }
}

{
  "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.

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

collection_id

string

required

Collection ID, or the collection slug when authenticating with an API key.

Body

application/json

A new field. Its type decides the options configuration takes.

name

string

required

key

string

required

The field's key in records' data, filters and sorts. Reserved for records' own attributes, and a few kept for later: id, object, collection, data, status, published_at, created_at, updated_at, deleted, deleted_at, purge_after, revision and schema_version.

type

any

required

boolean

Every record must have a value. Not available for boolean fields (a boolean is true or false; no value reads as false).

multiple

boolean

A list of distinct values (a repeated value is refused with duplicate_value, an empty string with blank_value). Not available for boolean, long_text, rich_text and json fields.

configuration

object

Plain text up to 10,000 characters, or a format.

Show child attributes

Response

The created field.

A field, typed by its type, which also decides the options its configuration takes.

string

required

Stable field ID. Never changes, even when the field is renamed.

Example:

"fld_01J9ZQ3F8X5W2K7M4N6P0R1S2T"

object

any

required

collection_id

string

required

name

string

required

Display name. Safe to change.

key

string

required

Key used in record data. Part of the API contract.

required

boolean

required

Every record must have a value. Not available for boolean fields (a boolean is true or false; no value reads as false).

multiple

boolean

required

A list of distinct values (a repeated value is refused with duplicate_value, an empty string with blank_value). Not available for boolean, long_text, rich_text and json fields.

position

integer

required

Where the field sorts in the collection's order, lowest first. New fields are added last; PUT /v1/collections/{collection_id}/field-order changes the order, numbering the fields from 0.

deleted_at

string<date-time> | null

required

When the field was deleted; null unless it is. Its values stay hidden in records until it is restored or purged.

purge_after

string<date-time> | null

required

When a deleted field and its values are removed for good, unless restored first.

aliases

object[]

required

Old keys of a renamed field that still work until expires_at: record data also carries the value under them, and writes, filters, sorts and expand accept them. Responses about the collection then have Deprecation and Sunset headers.

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"

type

any

required

configuration

object

required

Plain text up to 10,000 characters, or a format.

Show child attributes