The field object

• object string: "field"

• id uuid

• type string (enum):

  • "date"

  • "text"

  • "number"

  • "currency"

  • "select"

  • "multiSelect"

  • "multiCollaborator"

  • "createdBy"

  • "lastUpdatedBy"

  • "createdAt"

  • "lastUpdatedAt"

• name string

• config object (optional): Depends on the type, see below for more information.

Field types and values

The field type and config define which value the field can be set to on an item. The value returned when reading an item and the value accepted when writing can differ — this is noted per type below.

date

• config object

  • includeTime boolean

• Field value (read): date or datetime (depending on the includeTime config option)

• Field value (write): a date string matching the field's configuration — e.g. "2025-01-20" when includeTime is false, or an ISO 8601 datetime such as "2025-01-20T10:30:00.000Z" when includeTime is true

text

• config: This type is not configurable.

• Field value: string

number

• config object

  • fractionDigits number (optional)

• Field value: number

currency

• config object

  • fractionDigits number (optional)

  • currency string

• Field value: number

select

• config object

  • options Array[object]

    • id uuid

    • name string

• Field value (read): an object from the configured options

  • id uuid

  • name string

• Field value (write): the option's name string, its id uuid, or the option object — so a value read from the API can be written back unchanged

multiSelect

• config object

  • options Array[object]

    • id uuid

    • name string

• Field value (read): an Array of objects from the configured options

  • id uuid

  • name string

• Field value (write): an Array of option names, ids, or option objects

multiCollaborator

• config: This type is not configurable.

• Field value: Array[uuid] (an array of user IDs)

createdBy

• config: This type is not configurable.

• Field value: uuid (user ID)

• Read-only: managed automatically and cannot be set on an item.

lastUpdatedBy

• config: This type is not configurable.

• Field value: uuid (user ID)

• Read-only: managed automatically and cannot be set on an item.

createdAt

• config object

  • includeTime boolean

• Field value: date or datetime (depending on the includeTime config option)

• Read-only: managed automatically and cannot be set on an item.

lastUpdatedAt

• config object

  • includeTime boolean

• Field value: date or datetime (depending on the includeTime config option)

• Read-only: managed automatically and cannot be set on an item.

Get fields

Fields are returned as part of the workspace object.

Create a field

Endpoint: POST /v0/fields

The new field is added to the workspace's fields array (see Workspaces).

Body:

• workspaceId uuid: The ID of the workspace to create the field in.

• type string (enum): The field type (see the field object).

• name string (optional): Auto-generated from the type if omitted. Must be unique within the workspace (case-insensitive).

• config object: Type-specific configuration (see Field types and values). Required for the types that have a config, omitted for the others. For select/multiSelect, provide options as [{ "name": ..., "color": ... }] — option ids are generated automatically if omitted.

• index integer (optional): The zero-based position of the field among the workspace's fields. Defaults to the end.

Example request

curl https://api.nuclino.com/v0/fields \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "workspaceId": "127a8c4a-b3c6-4a42-8fef-b6c521e6c8cf",
        "type": "select",
        "name": "Status",
        "config": { "options": [ { "name": "Todo", "color": "red" }, { "name": "Done", "color": "green" } ] }
      }'

Example response

{
  "status": "success",
  "data": {
    "object": "field",
    "id": "5a1c0d2e-7b4f-4c8a-9e31-2d6f0b8a4c11",
    "type": "select",
    "name": "Status",
    "config": {
      "options": [
        { "id": "0b2e4d7c-1f3a-4b9c-8a21-7c5e9d0f2a64", "name": "Todo", "color": "red" },
        { "id": "c93a17e8-5d22-4f0b-bb6e-1a8f3c2d9e07", "name": "Done", "color": "green" }
      ]
    }
  }
}

Update a field

Endpoint: PUT /v0/fields/:id

This replaces the field definition, so provide its full type and config. Destructive changes — changing the type, or removing select/multiSelect options — may delete those values from items in the workspace. To keep existing options, include them (with their existing ids) in config.options.

Body:

• workspaceId uuid: The ID of the workspace the field belongs to.

• type string (enum): The field type.

• name string (optional): Auto-generated from the type if omitted. Must be unique within the workspace.

• config object: Type-specific configuration (see Field types and values).

Example request

curl https://api.nuclino.com/v0/fields/5a1c0d2e-7b4f-4c8a-9e31-2d6f0b8a4c11 \
  -X PUT \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "workspaceId": "127a8c4a-b3c6-4a42-8fef-b6c521e6c8cf",
        "type": "select",
        "name": "State",
        "config": {
          "options": [
            { "id": "0b2e4d7c-1f3a-4b9c-8a21-7c5e9d0f2a64", "name": "Todo", "color": "red" },
            { "id": "c93a17e8-5d22-4f0b-bb6e-1a8f3c2d9e07", "name": "Done", "color": "green" }
          ]
        }
      }'

Example response

{
  "status": "success",
  "data": {
    "object": "field",
    "id": "5a1c0d2e-7b4f-4c8a-9e31-2d6f0b8a4c11",
    "type": "select",
    "name": "State",
    "config": {
      "options": [
        { "id": "0b2e4d7c-1f3a-4b9c-8a21-7c5e9d0f2a64", "name": "Todo", "color": "red" },
        { "id": "c93a17e8-5d22-4f0b-bb6e-1a8f3c2d9e07", "name": "Done", "color": "green" }
      ]
    }
  }
}

Delete a field

Endpoint: DELETE /v0/fields/:id

This removes the field and its values from every item in the workspace.

Query parameters:

• workspaceId uuid: The ID of the workspace the field belongs to.

Example request

curl 'https://api.nuclino.com/v0/fields/5a1c0d2e-7b4f-4c8a-9e31-2d6f0b8a4c11?workspaceId=127a8c4a-b3c6-4a42-8fef-b6c521e6c8cf' \
  -X DELETE \
  -H "Authorization: YOUR_API_KEY"

Example response

{
  "status": "success",
  "data": { "id": "5a1c0d2e-7b4f-4c8a-9e31-2d6f0b8a4c11" }
}

Get field values of an item

Field values are returned as part of the item object.

Set field values of an item

Field values are set when creating or updating an item, via the fields attribute of POST /v0/items and PUT /v0/items/:id (see Items and Collections). The fields attribute is an object that maps field names to values.

• Only the fields you include are changed — other field values on the item are left untouched.

• Set a field to null to clear its value.

• Field values can only be set on items, not collections.

• The read-only field types (createdBy, lastUpdatedBy, createdAt, lastUpdatedAt) cannot be set.

• For multiSelect and multiCollaborator, send a non-empty array; to remove all values, set the field to null (an empty array is not accepted).

• If any field in the request is unknown, read-only, or has an invalid value, the whole request is rejected and no values are changed.

Example request

curl https://api.nuclino.com/v0/items/aaf6d580-565d-497b-9ff3-b32075de3f4c \
  -X PUT \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "fields": {
          "Status": "In progress",
          "Tags": ["Backend", "Urgent"],
          "Priority": 1,
          "Due date": "2025-01-20",
          "Assignees": ["2e96f3bb-c742-4164-af2c-151ab2fd346b"],
          "Notes": null
        }
      }'