curl --request POST \
--url https://api.nohead.io/v1/collections/{collection_id}/migrations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"field_id": "fld_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
"configuration": {
"description": "<string>",
"searchable": true,
"filterable": true,
"sortable": true,
"min_length": 1,
"max_length": 1,
"unique": true
},
"multiple": true,
"required": true,
"backfill": "<unknown>",
"on_invalid": "fail",
"time_zone": "Europe/Copenhagen"
}
'import { Nohead } from "@nohead/sdk"
const nohead = new Nohead()
const result = await nohead.migrations.create("posts", {
field_id: "fld_01J9ZQ3F8X",
type: "long_text",
dry_run: true,
})
from nohead import Nohead
nohead = Nohead()
result = nohead.migrations.create(
"posts", field_id="fld_01J9ZQ3F8X", type="long_text", dry_run=True
)
require "nohead"
nohead = Nohead::Client.new
result = nohead.migrations.create("posts", field_id: "fld_01J9ZQ3F8X", type: "long_text", dry_run: true)
{
"object": "field_migration_preview",
"field_id": "<string>",
"from": {
"type": "text",
"configuration": {
"description": "<string>",
"searchable": true,
"filterable": true,
"sortable": true,
"min_length": 1,
"max_length": 1,
"format": "slug",
"unique": true
},
"multiple": true,
"required": true
},
"to": {
"type": "text",
"configuration": {
"description": "<string>",
"searchable": true,
"filterable": true,
"sortable": true,
"min_length": 1,
"max_length": 1,
"format": "slug",
"unique": true
},
"multiple": true,
"required": true
},
"conversion": "safe",
"records": {
"total": 123,
"unchanged": 123,
"converted": 123,
"backfilled": 123,
"cleared": 123,
"invalid": 123
},
"samples": [
{
"record_id": "<string>",
"deleted_at": "2023-11-07T05:31:56Z",
"outcome": "converted",
"before": "<unknown>",
"after": "<unknown>",
"error": {
"code": "<string>",
"message": "<string>"
}
}
]
}{
"id": "mig_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
"object": "field_migration",
"collection_id": "<string>",
"field_id": "<string>",
"status": "pending",
"from": {
"type": "text",
"configuration": {
"description": "<string>",
"searchable": true,
"filterable": true,
"sortable": true,
"min_length": 1,
"max_length": 1,
"format": "slug",
"unique": true
},
"multiple": true,
"required": true
},
"to": {
"type": "text",
"configuration": {
"description": "<string>",
"searchable": true,
"filterable": true,
"sortable": true,
"min_length": 1,
"max_length": 1,
"format": "slug",
"unique": true
},
"multiple": true,
"required": true
},
"backfill": {
"value": "<unknown>"
},
"on_invalid": "fail",
"time_zone": "<string>",
"records": {
"total": 123,
"unchanged": 123,
"converted": 123,
"backfilled": 123,
"cleared": 123,
"invalid": 123
},
"failure": {
"message": "<string>"
},
"schema_change_id": "<string>",
"cancel_requested_at": "2023-11-07T05:31:56Z",
"actor": {
"type": "user",
"id": "<string>",
"name": "<string>"
},
"via": "ui",
"note": "<string>",
"request_id": "<string>",
"created_at": "2026-09-27T12:00:00.000Z",
"started_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z"
}{
"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>"
}
]
}
}Migrate a field
Changes one of the collection’s fields (field_id) in a way that
rewrites existing record values: its type, multiple, a stricter
configuration, a date’s include_time, or making it required
with a backfill for records that have no value.
Every record is checked first. With dry_run=true the result is a
preview: counts per outcome and sample records, nothing written. Without
it, a migration whose values do not all convert is refused (422)
unless on_invalid is clear; otherwise it is accepted (202) and
applied in the background. Poll GET /v1/migrations/{migration_id}.
While a migration is pending or running, schema writes to the collection
return 409, and record writes do once it is running (a pending one may
wait for others to finish). A value written while it waits that does
not convert fails the migration, or is cleared with on_invalid: clear. Each record whose data changes gets a
migrate revision, so cleared or converted values stay recoverable.
A dry run’s preview shows sample record values, so it also needs
records:read.
curl --request POST \
--url https://api.nohead.io/v1/collections/{collection_id}/migrations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"field_id": "fld_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
"configuration": {
"description": "<string>",
"searchable": true,
"filterable": true,
"sortable": true,
"min_length": 1,
"max_length": 1,
"unique": true
},
"multiple": true,
"required": true,
"backfill": "<unknown>",
"on_invalid": "fail",
"time_zone": "Europe/Copenhagen"
}
'import { Nohead } from "@nohead/sdk"
const nohead = new Nohead()
const result = await nohead.migrations.create("posts", {
field_id: "fld_01J9ZQ3F8X",
type: "long_text",
dry_run: true,
})
from nohead import Nohead
nohead = Nohead()
result = nohead.migrations.create(
"posts", field_id="fld_01J9ZQ3F8X", type="long_text", dry_run=True
)
require "nohead"
nohead = Nohead::Client.new
result = nohead.migrations.create("posts", field_id: "fld_01J9ZQ3F8X", type: "long_text", dry_run: true)
{
"object": "field_migration_preview",
"field_id": "<string>",
"from": {
"type": "text",
"configuration": {
"description": "<string>",
"searchable": true,
"filterable": true,
"sortable": true,
"min_length": 1,
"max_length": 1,
"format": "slug",
"unique": true
},
"multiple": true,
"required": true
},
"to": {
"type": "text",
"configuration": {
"description": "<string>",
"searchable": true,
"filterable": true,
"sortable": true,
"min_length": 1,
"max_length": 1,
"format": "slug",
"unique": true
},
"multiple": true,
"required": true
},
"conversion": "safe",
"records": {
"total": 123,
"unchanged": 123,
"converted": 123,
"backfilled": 123,
"cleared": 123,
"invalid": 123
},
"samples": [
{
"record_id": "<string>",
"deleted_at": "2023-11-07T05:31:56Z",
"outcome": "converted",
"before": "<unknown>",
"after": "<unknown>",
"error": {
"code": "<string>",
"message": "<string>"
}
}
]
}{
"id": "mig_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
"object": "field_migration",
"collection_id": "<string>",
"field_id": "<string>",
"status": "pending",
"from": {
"type": "text",
"configuration": {
"description": "<string>",
"searchable": true,
"filterable": true,
"sortable": true,
"min_length": 1,
"max_length": 1,
"format": "slug",
"unique": true
},
"multiple": true,
"required": true
},
"to": {
"type": "text",
"configuration": {
"description": "<string>",
"searchable": true,
"filterable": true,
"sortable": true,
"min_length": 1,
"max_length": 1,
"format": "slug",
"unique": true
},
"multiple": true,
"required": true
},
"backfill": {
"value": "<unknown>"
},
"on_invalid": "fail",
"time_zone": "<string>",
"records": {
"total": 123,
"unchanged": 123,
"converted": 123,
"backfilled": 123,
"cleared": 123,
"invalid": 123
},
"failure": {
"message": "<string>"
},
"schema_change_id": "<string>",
"cancel_requested_at": "2023-11-07T05:31:56Z",
"actor": {
"type": "user",
"id": "<string>",
"name": "<string>"
},
"via": "ui",
"note": "<string>",
"request_id": "<string>",
"created_at": "2026-09-27T12:00:00.000Z",
"started_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z"
}{
"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
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
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.
1 - 255First-party client identifier recorded in history (e.g. cli/0.3.1). Informational only.
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, or the collection slug when authenticating with an API key.
Query Parameters
Body
The field, and the parts of its definition to change; omitted parts stay as they are.
One of the collection's fields (422 otherwise).
"fld_01J9ZQ3F8X5W2K7M4N6P0R1S2T"
text, long_text, rich_text, integer, decimal, date, boolean, enum, asset, relation, json The complete new configuration. When the type changes and this is omitted, only description, searchable, filterable and sortable carry over.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
- Option 11
Show child attributes
Show child attributes
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.
Value for active records that have no value, validated like a record value of the new definition; an empty string is refused with blank_value.
clear removes values that cannot be converted (or backfills them); fail refuses the migration.
fail, clear When a date field's include_time is turned off: the IANA time zone
(e.g. Europe/Copenhagen) whose day each moment falls on. Default:
the field's time_zone, else UTC. Refused for any other change.
"Europe/Copenhagen"
Response
A preview (dry runs only).
Show child attributes
Show child attributes
Show child attributes
Show child attributes
safe: every value converts unchanged in meaning. convertible: every value converts, the representation changes. conditional: some values may not convert.
safe, convertible, conditional Records by outcome, including soft-deleted records (which are converted but never backfilled).
Show child attributes
Show child attributes
Up to 10 affected records, invalid ones first.
Show child attributes
Show child attributes