Create a field definition | Kibana API documentation

Create a field definition Technical preview

POST /api/cases/field_definitions

Spaces method and path for this operation:

post /s/{space_id}/api/cases/field_definitions

Refer to Spaces for more information.

Creates a field definition in the field library. You must have the "Manage templates" sub-privilege for the Cases feature of the owning solution. Requires the Cases feature to be enabled in the space. Use dry_run=true to validate the request without writing anything.

Query parameters

dry_run boolean

When true, runs authorization, body, and name-uniqueness validation without creating the field definition. Returns { "valid": true } on success.

Default value is false.

application/json

Body Required

definition string Required

The field definition as a YAML string describing a single field (type, label, control, metadata).

Maximum length is 30000.
description string

Optional human-readable description of the field's purpose.

Maximum length is 1000.
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

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.

Minimum length is 1, maximum length is 50.
owner string Required

The application that owns this field definition.

Minimum length is 1, maximum length is 30.

Responses

200 application/json

Indicates a successful call. Returns the created field definition, or { "valid": true } when dry_run=true.
One of:
Field definition response object object-2 object
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.

Hide attributes Show attributes

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

Position of a global field in the case details view. Assigned by the server and changed via the Field Library reorder controls.

Minimum value is 0.

fieldDefinitionId string 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.

Maximum length is 36.

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 Required

The application that owns this field definition.

Maximum length is 50.
Hide attribute Show attribute

valid boolean Required
400 application/json

The request body is invalid, the YAML definition is malformed, the name does not match the YAML definition's name, or the owner already has 200 field definitions.
Hide response attributes Show response attributes object
- error string
- message string
- statusCode integer
401 application/json

Authorization information is missing or invalid.
Hide response attributes Show response attributes object
- error string
- message string
- statusCode integer
403 application/json

The user does not have the manage templates privilege for the owner.
Hide response attributes Show response attributes object
- error string
- message string
- statusCode integer
409 application/json

A field definition with the same name already exists for the owner.
Hide response attributes Show response attributes object
- error string
- message string
- statusCode integer

POST /api/cases/field_definitions

curl \
 --request POST 'https://localhost:5601/api/cases/field_definitions' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
  "definition": "name: priority\nlabel: Priority\ntype: keyword\ncontrol: SELECT_BASIC\nmetadata:\n  options: [low, medium, high]\n  default: medium\n",
  "description": "Ticket priority level.",
  "isGlobal": false,
  "name": "priority",
  "owner": "cases"
}'

Request example

{
  "definition": "name: priority\nlabel: Priority\ntype: keyword\ncontrol: SELECT_BASIC\nmetadata:\n  options: [low, medium, high]\n  default: medium\n",
  "description": "Ticket priority level.",
  "isGlobal": false,
  "name": "priority",
  "owner": "cases"
}

Response examples (200)

{
  "definition": "name: priority\nlabel: Priority\ntype: keyword\ncontrol: SELECT_BASIC\nmetadata:\n  options: [low, medium, high]\n  default: medium\n",
  "description": "Ticket priority level.",
  "fieldDefinitionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "isGlobal": false,
  "name": "priority",
  "owner": "cases"
}

Response examples (400)

{
  "error": "Bad Request",
  "message": "Template [invalid-template-id] not found for owner [cases]",
  "statusCode": 400
}

Response examples (401)

{
  "error": "Unauthorized",
  "message": "Unable to authenticate with the provided credentials.",
  "statusCode": 401
}

Response examples (403)

{
  "error": "Forbidden",
  "message": "Unauthorized to access cases",
  "statusCode": 403
}

Response examples (409)

{
  "error": "Conflict",
  "message": "Template name \"Security incident\" already exists for owner \"cases\"",
  "statusCode": 409
}