---
title: "Create a field definition"
method: POST
path: "/api/cases/field_definitions"
tags: ["cases"]
---

# Create a field definition

`POST /api/cases/field_definitions`

**Spaces method and path for this operation:**

<div><span class="operation-verb post">post</span>&nbsp;<span class="operation-path">/s/{space_id}/api/cases/field_definitions</span></div>

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-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

## Request body

- CasesFieldDefinitionWriteRequest — The body for creating or updating a field definition. Resource limits (enforced on write; a violation returns `400`): an owner may have at most 200 field definitions per space. The `definition` string may not exceed 30000 characters. Identity constraints: the `name` property must match the `name` key in the YAML `definition`. When `name` is omitted, the server extracts it from the `definition` YAML automatically. Once created, a field's `name` and YAML `type` are immutable — they determine the key under which case values are stored. An attempt to change either returns `409` with `attributes.code = "field_identity_immutable"` and `attributes.changed` listing which identity attributes were modified.
  - `definition` string, required — The field definition as a YAML string describing a single field (type, label, control, metadata).
  - `description` string — 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 — 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.
  - `owner` string, required — The application that owns this field definition.

## Response `200`

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

- union
  - CasesFieldDefinitionResponse — 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 — Position of a global field in the case details view. Assigned by the server and changed via the Field Library reorder controls.
    - `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.
    - `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.
  - object
    - `valid` boolean, required

## Other responses

- `400` — 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.
- `401` — Authorization information is missing or invalid.
- `403` — The user does not have the manage templates privilege for the owner.
- `409` — A field definition with the same name already exists for the owner.

---

[API](https://skmtc.dev/elastic/apis/kibana-apis.md) · [All operations](https://skmtc.dev/elastic/apis/kibana-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/elastic/apis/kibana-apis/revisions/84f30e7da461?raw)