create_folder
Creates a Jira/Zephyr test folder for cases, plans, or runs/cycles using a full root path; missing parent folders can be added when needed.
Instructions
Create a folder for test cases, test plans or test runs / test cycles (POST /folder). name is the FULL path from the root, not a single segment, and every segment must be non-empty and not blank — "/" alone, "/A//B", a trailing "/" and a whitespace-only segment ("/A/ ") are rejected before any HTTP call because the API would create a permanently nameless folder from them. Spaces around a real name are legal and are NOT trimmed. The two rules surface differently: a missing leading "/" is caught by the input schema (an MCP input-validation error), while empty or blank segments are caught by the tool itself (a plain "Invalid folder path ..." message). The other tools never create folders implicitly: create_test_case, create_test_run and create_test_plan fail with 400 on an unknown folder. Not idempotent: an existing path fails with 400 "The folder already exists" and no retry is attempted. With recursive=true (the default) any OTHER 400 on the full path triggers the fallback — every parent prefix is created from the root and the full path is retried once; 403, 409 and 5xx propagate unchanged, so a permission problem is never mistaken for a missing parent. On builds where POST /folder already creates missing ancestors itself that fallback never fires — the reference build is one of them: a two-level-deep new path succeeds even with recursive=false, so recursive is effectively a no-op there. Each folder type has its own tree, so the same path must be created once per type. The public Server/DC API v1 cannot LIST folders, so keep the numeric id returned by create_folder — rename_folder and delete_folder need it (otherwise it can only be found in the Jira UI, or with get_folder_tree when the internal API is enabled). Returns { id, name, type } — id is the id of the LAST segment only, so ancestors created along the way have ids this call never reports (find them with get_folder_tree).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Full path of the folder to create, from the root, starting with "/", e.g. "/Regression/Payments" — every segment is a folder level and must contain at least one non-whitespace character. Segments are stored verbatim: leading and trailing spaces are NOT trimmed, so "/A/ B " and "/A/B" are different folders, but a segment made only of spaces is rejected. | |
| type | Yes | Folder kind: TEST_CASE (test case folders), TEST_PLAN (test plan folders) or TEST_RUN (test cycle folders) | |
| recursive | No | Create missing parent folders after a 400 on the full path (default true). Client-side only — never sent to the API. | |
| projectKey | No | Jira project key, e.g. "PROJ"; defaults to ZEPHYR_DEFAULT_PROJECT_KEY when omitted |