Update a field definition

Base URL: https://{kibana_url}

PUT /api/cases/field_definitions/{field_definition_id}
PUT /s/{space_id}/api/cases/field_definitions/{field_definition_id}

Auth

Updates editable attributes of a field definition. Server-managed attributes (displayOrder, legacyKey) are preserved. You must have the "Manage templates" sub-privilege for the Cases feature of the owning solution. A field's name and YAML type are immutable after creation — an attempt to change either returns 409 with attributes.code = "field_identity_immutable" and attributes.changed listing which identity attributes were modified. Setting isGlobal to false when the field is linked to an active custom field in the Cases configuration returns 409; otherwise demotion is allowed. Requires the Cases feature to be enabled in the space. Use dry_run=true to validate the request without writing anything.

Path parameters

space_id string optional: An identifier for the space. If space_id is not provided in the URL, the default space is used. Refer to Spaces for more information.
field_definition_id string · max length: 36 required: The identifier for the field definition.

Query parameters

dry_run boolean · default: false: When true, runs authorization, body, and identity-immutability validation without updating the field definition. Returns { "valid": true } on success.

Request body

definition string · max length: 1000000 required: The field definition as a YAML string describing a single field (type, label, control, metadata).
description string · max length: 1000: Optional human-readable description of the field's purpose.
isGlobal boolean: When true, this field is rendered in every case for this owner, regardless of the template used. Global fields cannot be demoted (set to false) while they are linked to an active custom field in the Cases configuration.
name string · min length: 1 · max length: 1000: The field name, unique per owner (case-insensitive). Must match the name key inside the YAML definition. When omitted, the name is extracted from the definition YAML automatically. Immutable after creation. Unlike POST, the 50-character limit is not enforced on PUT so that definitions with legacy names that exceed the limit remain modifiable.
owner string · min length: 1 · max length: 30 required: The application that owns this field definition.

Responses

Indicates a successful call. Returns the updated field definition, or { "valid": true } when dry_run=true.

application/json

One of:

A field definition from the field library. The legacyKey attribute, which is a server-managed link to a migrated custom field, is not included in the public API response.

definition string required: The field definition as a YAML string. New definitions are limited to 30 000 characters, but existing definitions created via internal tooling may be longer.
description string: Optional human-readable description of the field's purpose.
displayOrder integer · min: 0: Position of a global field in the case details view. Assigned by the server and changed via the Field Library reorder controls.
fieldDefinitionId string · max length: 36 required: Unique server-assigned identifier for the field definition (UUID). May be UUIDv4 for definitions created through the public API, or UUIDv5 for definitions created by internal migration processes.
isGlobal boolean: When true, this field is rendered in every case regardless of which template the case uses.
name string required: The field name. Must match the name property in the YAML definition and is unique per owner (case-insensitive). Immutable after creation.
owner string · max length: 50 required: The application that owns this field definition.

The request body is invalid, the YAML definition is malformed, the name does not match the YAML definition's name, or the owner would be changed.

application/json

error string
message string
statusCode integer

Authorization information is missing or invalid.

application/json

error string
message string
statusCode integer

The user does not have the manage templates privilege for the owner.

application/json

error string
message string
statusCode integer

The field definition was not found.

application/json

error string
message string
statusCode integer

A field's name or type cannot be changed after creation, or a global field cannot be demoted while linked to an active custom field.

application/json

Any of:

Identity-immutable conflict — name or type was changed.

attributes object required
error string required
message string required
statusCode integer required

Path parameters

Query parameters

Request body { }

Responses

Request body