---
title: "Update custom field"
method: PUT
path: "/custom-field/{id}"
tags: ["Custom Fields"]
---

# Update custom field

`PUT /custom-field/{id}`

## Request

- Base URL: `https://cloud.kaneo.app/api`
- URL: `https://cloud.kaneo.app/api/custom-field/{id}`
- Auth: HTTP bearer

Update a custom field's name, required flag, default, or options. The type can't change, except between dropdown and multiselect. Options that tasks still use can't be removed or renamed; the request is rejected instead of changing task values.

## Path parameters

- `id` string, required

## Request body

- object
  - `name` string: New name for the field. Cannot be blank.
  - `type` 'text' | 'number' | 'date' | 'dropdown' | 'boolean' | 'multiselect': Only `dropdown` and `multiselect` can switch between each other. Task values are converted, and switching to `dropdown` is rejected while a task has more than one option picked. Any other type change is rejected.
  - `required` boolean: Whether every task must have a value. Turning it on needs a default, which fills tasks that have no value yet.
  - `defaultValue` string, nullable: Value new tasks start with. Send `null` or an empty string to clear it. Multiselect defaults are a JSON array of options.
  - `options` string[]: The full option list for dropdown and multiselect fields, in display order. Adding and reordering options is always allowed. Removing or renaming an option that a task still uses is rejected with 400, so task values are never changed silently.
  - `hiddenOptions` string[]: Options to retire without removing them: tasks keep their existing selections, but hidden options can't be picked anew or used as the default. Must be a subset of `options`. Omit to keep the current hidden options that are still options.

## Response `200`

The updated custom field

- CustomFieldDefinition
  - `id` string, required
  - `projectId` string, required
  - `name` string, required
  - `type` string, required
  - `required` boolean, required
  - `defaultValue` string, nullable, required
  - `options` unknown
  - `hiddenOptions` string[], required: Options no longer offered for new selections. Tasks that already use them keep them.
  - `position` number, required
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required

## Other responses

- `400`: Invalid body, a type change, or removing an option that tasks still use
- `401`: Missing or invalid credentials
- `403`: No access to the project, or missing project:update permission
- `404`: Custom field not found
- `429`: The API key exceeded its rate limit or usage quota. Wait the number of seconds in Retry-After before retrying. The X-RateLimit headers are sent only when the rate limit was hit.

## Changes

- **2026-10-26** `84eec352f21c`: 2 info
  - added the new optional request property `hiddenOptions`
  - added the required property `hiddenOptions` to the response with the `200` status
- **2026-10-26** `cf382d653cdc`: 1 breaking, 1 warning
  - removed the required property `hiddenOptions` from the response with the `200` status
  - removed the request property `hiddenOptions`
- **2026-10-26** `82973bd64be8`: 2 info
  - added the new optional request property `hiddenOptions`
  - added the required property `hiddenOptions` to the response with the `200` status
- **2026-10-12** `d3eba51ae921`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/usekaneo/apis/kaneo-api/changes/custom-field/:id/put.md)

---

[API](https://skmtc.dev/usekaneo/apis/kaneo-api.md) - [All operations](https://skmtc.dev/usekaneo/apis/kaneo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/usekaneo/apis/kaneo-api/revisions/93f78789100c?raw)