Update a field definition Technical preview

PUT /api/cases/field_definitions/{field_definition_id}
Api key auth Basic auth

Spaces method and path for this operation:

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

Refer to Spaces for more information.

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

  • field_definition_id string Required

    The identifier for the field definition.

    Maximum length is 36.

Query parameters

  • dry_run boolean

    When true, runs authorization, body, and identity-immutability validation without updating 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 1000000.

  • 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. Unlike POST, the 50-character limit is not enforced on PUT so that definitions with legacy names that exceed the limit remain modifiable.

    Minimum length is 1, maximum length is 1000.

  • 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 updated field definition, or { "valid": true } when dry_run=true.

    One of:
    Field definition response object object-2 object
  • 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 would be changed.

    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
  • 404 application/json

    The field definition was not found.

    Hide response attributes Show response attributes object
    • error string
    • message string
    • statusCode integer
  • 409 application/json

    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.

    Any of:
    object-1 object Unsuccessful cases API response object
PUT /api/cases/field_definitions/{field_definition_id} 
curl \
 --request PUT 'https://localhost:5601/api/cases/field_definitions/{field_definition_id}' \
 --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 (404) 
{
  "error": "Not Found",
  "message": "Saved object [cases-template/9da1ea2a-09f8-4d0e-bf9d-09bf8c9d0f42] not found",
  "statusCode": 404
}
Response examples (409) 
{
  "error": "Conflict",
  "message": "Template name \"Security incident\" already exists for owner \"cases\"",
  "statusCode": 409
}