---
title: "POST /create-test-case-definition"
method: POST
path: "/create-test-case-definition"
---

# POST /create-test-case-definition

`POST /create-test-case-definition`

Create a new test case definition

## Request body

- object
  - `name` string, required — Name of the test case definition
  - `response_engine` union, required — Response engine for test cases. Custom LLM is not supported.
    - ResponseEngineRetellLm
      - `type` 'retell-llm', required — type of the Response Engine.
      - `llm_id` string, required — id of the Retell LLM Response Engine.
      - `version` number, nullable — Version of the Retell LLM Response Engine.
    - ResponseEngineConversationFlow
      - `type` 'conversation-flow', required — type of the Response Engine.
      - `conversation_flow_id` string, required — ID of the Conversation Flow Response Engine.
      - `version` number, nullable — Version of the Conversation Flow Response Engine.
  - `user_prompt` string, required — User prompt to simulate in the test case
  - `metrics` string[], required — Array of metric names to evaluate
  - `dynamic_variables` object — Dynamic variables to inject into the response engine
  - `tool_mocks` ToolMock[] — Mock tool calls for testing
    - `tool_name` string, required — Name of the tool to mock
    - `input_match_rule` union, required
      - object
        - `type` 'any', required — Match any input of the tool
      - object
        - `type` 'partial_match', required — Match only calls with specific arguments
        - `args` object, required — Arguments to match. Only provided fields will be checked
    - `output` string, required — The output of the tool call that will be fed into the LLM. Should be a JSON string.
    - `result` boolean, nullable — For tool calls like transfer_call that require a boolean result. Optional for most tools.
  - `llm_model` 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-5' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5.5' | 'claude-4.5-sonnet' | 'claude-4.6-sonnet' | 'claude-4.5-haiku' | 'gemini-2.5-flash-lite' | 'gemini-3.0-flash' | 'gemini-3.1-flash-lite' — Available LLM models for agents.

## Response `201`

Test case definition created successfully

- TestCaseDefinition
  - `name` string, required — Name of the test case definition
  - `response_engine` union, required — Response engine for test cases. Custom LLM is not supported.
    - ResponseEngineRetellLm
      - `type` 'retell-llm', required — type of the Response Engine.
      - `llm_id` string, required — id of the Retell LLM Response Engine.
      - `version` number, nullable — Version of the Retell LLM Response Engine.
    - ResponseEngineConversationFlow
      - `type` 'conversation-flow', required — type of the Response Engine.
      - `conversation_flow_id` string, required — ID of the Conversation Flow Response Engine.
      - `version` number, nullable — Version of the Conversation Flow Response Engine.
  - `user_prompt` string, required — User prompt to simulate in the test case
  - `metrics` string[], required — Array of metric names to evaluate
  - `dynamic_variables` object, required — Dynamic variables to inject into the response engine
  - `tool_mocks` ToolMock[], required — Mock tool calls for testing
    - `tool_name` string, required — Name of the tool to mock
    - `input_match_rule` union, required
      - object
        - `type` 'any', required — Match any input of the tool
      - object
        - `type` 'partial_match', required — Match only calls with specific arguments
        - `args` object, required — Arguments to match. Only provided fields will be checked
    - `output` string, required — The output of the tool call that will be fed into the LLM. Should be a JSON string.
    - `result` boolean, nullable — For tool calls like transfer_call that require a boolean result. Optional for most tools.
  - `llm_model` 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-5' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5.5' | 'claude-4.5-sonnet' | 'claude-4.6-sonnet' | 'claude-4.5-haiku' | 'gemini-2.5-flash-lite' | 'gemini-3.0-flash' | 'gemini-3.1-flash-lite', required — Available LLM models for agents.
  - `test_case_definition_id` string, required — Unique identifier for the test case definition
  - `type` 'simulation', required — Type of test case definition
  - `creation_timestamp` integer, required — Timestamp when the test case definition was created (milliseconds since epoch)
  - `user_modified_timestamp` integer, required — Timestamp when the test case definition was last modified (milliseconds since epoch)

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `402` — Payment Required
- `429` — Too Many Requests
- `500` — Internal Server Error

## Changes

- **2026-05-07** `f1a0d7c1e36c` — 1 breaking, 1 info
  - removed the enum value `gemini-2.5-flash` of the request property `allOf[#/components/schemas/TestCaseDefinitionInput]/llm_model`
  - removed the `gemini-2.5-flash` enum value from the `allOf[#/components/schemas/TestCaseDefinitionInput]/llm_model` response property for the response status `201`
- **2026-04-28** `1b4a9d84942a` — 1 warning, 1 info
  - added the new `gpt-5.5` enum value to the `allOf[#/components/schemas/TestCaseDefinitionInput]/llm_model` response property for the response status `201`
  - added the new `gpt-5.5` enum value to the request property `allOf[#/components/schemas/TestCaseDefinitionInput]/llm_model`
- **2026-04-20** `8ee53928bf31` — 1 warning, 1 info
  - added the new `gemini-3.1-flash-lite` enum value to the `allOf[#/components/schemas/TestCaseDefinitionInput]/llm_model` response property for the response status `201`
  - added the new `gemini-3.1-flash-lite` enum value to the request property `allOf[#/components/schemas/TestCaseDefinitionInput]/llm_model`
- …earlier changes not shown

[Full history](https://skmtc.dev/retellai/apis/retell-sdk/changes/create-test-case-definition/post.md)

---

[API](https://skmtc.dev/retellai/apis/retell-sdk.md) · [All operations](https://skmtc.dev/retellai/apis/retell-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/retellai/retell-sdk/revisions/2a182bedbfc5/schema)