---
title: "Create a test case"
method: POST
path: "/v1/test-cases"
tags: ["test-cases"]
---

# Create a test case

`POST /v1/test-cases`

Create a new test case with an initial version snapshot.

## Headers

- `x-api-key` string

## Request body

- CreateTestCaseRequest — Request to create a new test case
  - `name` string, required — Test case name
  - `steps` TestStepInput[], required — Ordered list of test steps
    - `description` string, required — Single atomic action
    - `credential_id` string, nullable — Credential UUID if step needs auth
    - `kind` 'setup' | 'act' | 'verify', nullable — Phase of the test the step belongs to: 'setup' (preconditions, navigation to the screen under test), 'act' (the action being tested), or 'verify' (post-action assertion). Untagged steps are stored without a kind and are treated as untagged downstream.
  - `expected_result` string, required — Expected result after executing steps
  - `priority` string, nullable — Priority level
  - `description` string, nullable — Optional description
  - `category_id` string, nullable — Category ID to assign
  - `change_source` string, nullable — Origin of the change (e.g. 'api', 'mcp')
  - `variables` TestCaseVariableInput[], nullable — Declared variable schema. Referenced in step text via `{{name}}`. Values supplied at run creation time. Omit or pass [] for no variables.
    - `name` string, required — Identifier matching /^[a-z][a-z0-9_]*$/, up to 40 chars; unique within the test case
    - `type` string, required — One of "string" or "number"
    - `required` boolean — When true, callers must supply a value at run creation (unless a default is set). The frontend also prompts for this variable in the run form.
    - `default` unknown
    - `description` string, nullable — Optional human-readable description shown in tooltips and the run form.
  - `file_attachments` TestCaseFileAttachmentInput[], nullable — UI-compatible test-file attachments with per-association descriptions.
    - `file_id` string, required — ID of a test_files row with file_kind = 'test'
    - `description` string, nullable — Optional per-test-case description for this attachment.
  - `file_ids` string[], nullable — Legacy test-file attachment IDs. Used with null descriptions.

## Response `201`

Test case created

- CreateTestCaseResponse — Response after creating a test case
  - `id` string, required — Created test case ID
  - `name` string, required — Test case name
  - `version_id` string, required — Initial version ID
  - `files` TestCaseFileAttachmentOutput[] — Attached test files persisted for this test case.
    - `file_id` string, required — Attached test_files.id
    - `description` string, nullable — Per-association attachment description
    - `file_path` string, nullable — Storage path for the attached test file
    - `original_name` string, nullable — Original uploaded filename
    - `file_type` string, nullable — MIME type
    - `file_size` integer, nullable — File size in bytes
  - `warnings` VariableWarning[], nullable — Non-fatal signals about variables; absent when nothing to warn about.
    - `code` string, required — One of: 'undeclared_reference' (step references a name not declared), 'literal_collision' (declaring a new variable turns existing literal `{{x}}` text into a substitution), 'unknown_variable' (run supplied a variable not declared on the test case; dropped silently).
    - `message` string, required — Human-readable explanation

## Other responses

- `401` — Invalid or missing API key
- `422` — Validation Error
- `500` — Internal server error

---

[API](https://skmtc.dev/qualgent/apis/qualgent-api-service.md) · [All operations](https://skmtc.dev/qualgent/apis/qualgent-api-service/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/qualgent/qualgent-api-service/revisions/2372ed4904a6/schema)