---
type: api
title: Create a case template
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-createcasetemplatedefaultspace
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-createcasetemplatedefaultspace
products:
  - Kibana
---

# Create a case template

Availability:

- Server: `https://{kibana_url}`

## Paths

- `POST` `/api/cases/templates`
- `POST` `/s/{space_id}/api/cases/templates`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/authentication#apikeyauth)

## Description

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.

Creates a case template from a YAML definition. You must have the "Manage templates" sub-privilege for the Cases feature of the owning solution. Set `dry_run=true` to run the full validation (body, YAML definition, name uniqueness, authorization) without creating anything. Requires the Cases feature to be enabled in the space.

## Query String Parameters

- `dry_run` (boolean · default: false)
  When true, validates the request without creating the template and returns `{"valid": true}`.

## Request Body

`application/json`

- `definition` (string · max: 30000) — required
  The template definition as a YAML string: case defaults (name, severity, category, tags, assignees, connector, settings) and a `fields` array of inline field definitions or `$ref` entries pointing into the owner's field library. Stored field values appear on cases under `extended_fields` keys shaped `<field_name>_as_<storage_type>`.
- `description` (string · max: 1000) — optional
  A description of the template.
- `isEnabled` (boolean · default: true) — optional
  Disabled templates are hidden from the case creation flow.
- `name` (string · min: 1 · max: 50) — optional
  The template identity name, unique per owner (case-insensitive). May be omitted when the YAML definition provides a case-default title (`name:`), which is then used as the identity name.
- `owner` (enum) — required
  The application that owns the cases: Stack Management, Observability, or Elastic Security.
  Values: `cases`, `observability`, `securitySolution`
- `tags` ([] object · max: 200) — optional
  The words and phrases that help categorize templates. It can be an empty array.

## Responses

#### `200`

Indicates a successful call. Returns the created template, or `{"valid": true}` for a dry run.

`application/json`

One of:
- **Cases_template_v2_response**
  A case template (v2).
  - `author` (string · max: 1000)
    The username of the template author.
  - `definition` (object)
    The parsed template definition.
  - `definitionString` (string · max: 30000)
    The raw YAML definition string.
  - `deletedAt` (string) — nullable
    The date the template was soft-deleted, or null if active.
  - `description` (string · max: 30000)
    A human-readable description of the template.
  - `fieldCount` (integer)
    The number of fields defined in the template.
  - `fieldDefinitions` ([] object)
    Metadata about each field defined in the template.
    - `control` (string · max: 50)
    - `label` (string · max: 256)
    - `name` (string · max: 256)
    - `type` (string · max: 50)
  - `isDefault` (boolean)
    Whether this is the default template for its owner.
  - `isEnabled` (boolean)
    Whether the template is enabled.
  - `isLatest` (boolean)
    Whether this is the latest version of the template.
  - `lastUsedAt` (string)
    The date the template was last used to create a case.
  - `latestVersion` (integer)
    The latest version number of this template.
  - `name` (string · max: 100)
    The display name of the template.
  - `owner` (string · max: 50)
    The owning solution (e.g. cases, observability, securitySolution).
  - `tags` ([] object · max: 200)
    The words and phrases that help categorize templates. It can be an empty array.
  - `templateId` (string · max: 36)
    The unique identifier of the template, shared across all versions.
  - `templateVersion` (integer)
    The version number of this template revision.
  - `usageCount` (integer)
    The number of times this template has been used to create a case.
- **Cases_template_dry_run_response**
  Returned instead of the template when the request was sent with `dry_run=true`.
  - `valid` (enum)
    Always `true` — validation failures return a 4xx error instead.
    Values: `true`
#### `400`

The request body, YAML definition, or template name is invalid, or a resource limit was exceeded (max 200 templates per owner, max 200 fields per template).

`application/json`

- `error` (string)
- `message` (string)
- `statusCode` (integer)
#### `401`

Authorization information is missing or invalid.

`application/json`

- `error` (string)
- `message` (string)
- `statusCode` (integer)
#### `403`

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

`application/json`

- `error` (string)
- `message` (string)
- `statusCode` (integer)
#### `409`

A template with the same name already exists for the owner.

`application/json`

- `error` (string)
- `message` (string)
- `statusCode` (integer)
## Code Examples

#### Console

```console
POST /api/cases/templates
{
  "definition": "name: Security incident\nseverity: high\ntags: [security]\nfields:\n  - name: priority\n    label: Priority\n    type: keyword\n    control: SELECT_BASIC\n    metadata:\n      options: [low, medium, high]\n      default: medium\n",
  "description": "Default template for security incidents.",
  "isEnabled": true,
  "name": "Security incident",
  "owner": "cases",
  "tags": [
    "security"
  ]
}
```

#### curl

```curl
curl -X POST "https://{kibana_url}/api/cases/templates" \
  -H "Content-Type: application/json" \
  -d '{
  "definition": "name: Security incident\nseverity: high\ntags: [security]\nfields:\n  - name: priority\n    label: Priority\n    type: keyword\n    control: SELECT_BASIC\n    metadata:\n      options: [low, medium, high]\n      default: medium\n",
  "description": "Default template for security incidents.",
  "isEnabled": true,
  "name": "Security incident",
  "owner": "cases",
  "tags": [
    "security"
  ]
}'
```

## Response Examples

#### A case template.

```json
{
  "definition": {},
  "definitionString": "fields: []",
  "deletedAt": "null",
  "isLatest": true,
  "latestVersion": 1,
  "name": "My Template",
  "owner": "cases",
  "templateId": "9da1ea2a-09f8-4d0e-bf9d-09bf8c9d0f42",
  "templateVersion": 1
}
```

#### Dry-run validation succeeded without writing.

```json
{
  "valid": true
}
```

#### A template resource limit was exceeded.

```json
{
  "error": "Bad Request",
  "message": "A template cannot define more than 200 fields.",
  "statusCode": 400
}
```

#### Authorization information is missing or invalid.

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

#### The user does not have access to the requested resource.

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

#### A resource conflict occurred.

```json
{
  "error": "Conflict",
  "message": "Template name \u0022Security incident\u0022 already exists for owner \u0022cases\u0022",
  "statusCode": 409
}
```