Create a Zephyr Scale test case (POST /testcase). Returns { key, url } with a key like PROJ-T123. Constraints: the folder, if given, MUST already exist — the API never creates folders (use create_folder first); status and priority are case-sensitive internal names (defaults 'Draft'/'Approved'/'Deprecated' and 'High'/'Normal'/'Low'; instances may define custom ones); owner is a Jira user key like JIRAUSER10000 (resolve with find_jira_user); estimatedTime is in milliseconds. testScript formats: STEP_BY_STEP with steps (a step carrying testCaseKey is a 'Call to Test' that inlines another test case), PLAIN_TEXT with text, or BDD with text holding the full Gherkin document (stored verbatim).

Read a Zephyr Scale test case by key (GET /testcase/{testCaseKey}). Optionally restrict the payload with fields. STEP_BY_STEP scripts come back with per-step ids — those ids are required to edit steps safely via update_test_case (add_test_steps handles them automatically).

Search Zephyr Scale test cases with a TQL query (GET /testcase/search). Returns { startAt, maxResults, count, isLast, values }; isLast is the heuristic count < maxResults. Paginate with startAt (default 0) and maxResults (default 50; the API server-side default is 200).

TQL quick reference:

• Test case fields: projectKey, key, name, status, priority, component, folder, estimatedTime, labels, owner, issueKeys + custom fields (field name in double quotes).

• Test run (cycle) fields: ONLY projectKey and folder.

• Operators: =, >, >=, <, <=, IN; the only logical connector is AND (no OR).

• Syntax is strict: spaces around operators are mandatory, string values in double quotes. Folder paths start with "/" ("/" is the root). For single/multi-choice custom fields '=' does not work — use IN.

• Examples: projectKey = "PROJ" AND status = "Draft" AND priority = "High" projectKey = "PROJ" AND folder = "/Regression/Payments" projectKey = "PROJ" AND labels IN ("smoke", "ui") projectKey = "PROJ" AND "My Field" IN ("Value") key IN ("PROJ-T50", "PROJ-T90") projectKey = "PROJ" AND issueKeys IN ("PROJ-5")

Note: queries longer than 1500 characters (typically large IN lists) are automatically sent via POST /testcase/search, which is RESTRICTED to the fields projectKey, key and name, and to at most 2500 values in an IN list.

Update a Zephyr Scale test case (PUT /testcase/{testCaseKey}). PARTIAL update: only the fields you pass are changed; omitted fields keep their current values — never send empty placeholders. projectKey cannot be changed. STEP_BY_STEP step synchronization: when testScript.steps is passed, steps are matched by id — a step WITHOUT an id is CREATED, a step WITH an id is UPDATED, and any existing step MISSING from the list is DELETED. Therefore always pass the COMPLETE final list of steps, carrying over the ids of steps to keep (read them with get_test_case). To merely add steps, prefer add_test_steps, which performs that read-merge-write safely. Returns { key, url }.

Add steps to a STEP_BY_STEP test case without losing the existing ones. Composite operation: reads the test case, merges the new steps at the requested position while preserving existing step ids (so nothing is deleted), and writes the full list back. position: 'append' (default) adds after the last step, 'prepend' before the first, an integer inserts at that 0-based index (clamped to the current length). Only valid when the current script is STEP_BY_STEP or the test case has no script yet (a step-by-step script is then created); for a PLAIN_TEXT or BDD script use set_test_script instead. Returns { key, totalSteps }.

Replace a test case's ENTIRE script or change its format (PUT /testcase/{testCaseKey} with a full testScript). WARNING — destructive: switching a STEP_BY_STEP script to PLAIN_TEXT or BDD irreversibly deletes all existing steps, and a STEP_BY_STEP replacement deletes every existing step omitted from the list. Pass text for PLAIN_TEXT/BDD (for BDD the full Gherkin document, stored verbatim); pass steps for STEP_BY_STEP. Returns { key, url }.

Permanently delete a Zephyr Scale test case (DELETE /testcase/{testCaseKey}). This cannot be undone. Returns { deleted: true, key }.

Create multiple Zephyr Scale test cases in one call (POST /testcase/bulk). Each item accepts the same fields as create_test_case; an item without its own projectKey uses the shared projectKey parameter (or ZEPHYR_DEFAULT_PROJECT_KEY). The same constraints apply: folders must already exist, status/priority values are case-sensitive, owner is a Jira user key. Returns an array of { key, url } for the created test cases.

Link Jira issues to Zephyr Scale test cases in bulk (POST /testcase/link-issues). Each entry links one test case (testCaseKey, e.g. PROJ-T123) to one Jira issue (issueKey, e.g. PROJ-123); repeat a test case key across entries to link it to several issues. API limit: at most 2500 UNIQUE test case keys per call — validated locally before any request is sent.

List the Zephyr Scale test cases linked to a Jira issue (GET /issuelink/{issueKey}/testcases). Useful for traceability from a requirement or bug to its tests.

Create a Zephyr Scale folder for test cases, test plans or test runs (test cycles). name is the FULL path from the root and must start with "/", e.g. "/Regression/Payments". With recursive=true (default) missing parent folders are created automatically: if the API rejects the full path with 400, every parent prefix is created from the root and the full path is retried. Folders are NOT auto-created by create_test_case / create_test_run — create them with this tool first. The public Server/DC API v1 cannot LIST folders, so keep the numeric id returned by create_folder — rename_folder needs it (otherwise the id can only be found in the Jira UI).

Rename an existing Zephyr Scale folder by its numeric id (and optionally update its custom fields). name is the new name of that single folder segment, NOT a path — it must not contain "/" or "". The public Server/DC API v1 cannot LIST folders, so keep the numeric id returned by create_folder — rename_folder needs it (otherwise the id can only be found in the Jira UI).

Create a Zephyr Scale test run (test cycle; key like PROJ-R123). IMPORTANT API v1 limitation: a test run is IMMUTABLE after creation — there is no PUT /testrun/{key}. A run cannot be renamed, moved to another folder, and test cases cannot be added to or removed from it later; the set of items is fixed ONLY at creation time. The run status is computed automatically from the statuses of its items and cannot be set directly. Therefore pass the COMPLETE list of test cases in items now — each item may also carry full execution result fields (status, executedBy, executionTime, actualStartDate/actualEndDate, per-step scriptResults, etc.), which allows importing a run together with its results in a single call. To record or update executions of the included items afterwards, use the test result tools. Item/result statuses default to 'Not Executed', 'In Progress', 'Pass', 'Fail', 'Blocked' (case-sensitive; instances may define custom ones).

Read a Zephyr Scale test run (test cycle) by key, including its items. IMPORTANT API v1 limitation: a test run is IMMUTABLE after creation — there is no PUT /testrun/{key}. A run cannot be renamed, moved to another folder, and test cases cannot be added to or removed from it later; the set of items is fixed ONLY at creation time. The run status is computed automatically from the statuses of its items and cannot be set directly. Use get_test_run_results to page through the execution results of the run.

Search Zephyr Scale test runs (test cycles) with TQL. For test runs TQL supports ONLY the fields projectKey and folder, ONLY the operators = and IN, and AND as the only logical connector (no OR, no other fields). Syntax is strict: spaces around operators are mandatory, string values go in double quotes, folder paths start with "/" ("/" is the root). Examples: projectKey = "PROJ" · projectKey = "PROJ" AND folder = "/Regression". Returns { startAt, maxResults, count, isLast, values }.

Permanently delete a Zephyr Scale test run (test cycle) together with all its execution results. Since runs are immutable after creation, deleting and re-creating a run (create_test_run with the full desired items) is the only way to change its name, folder or composition.

Page through the execution results of a Zephyr Scale test run (test cycle) via the paginated endpoint GET /testrun/{key}/testresults/page (the flat non-paginated variant is deprecated and not used). An item of a run can have several executions; set onlyLastExecutions to true to get only the most recent execution per item. Returns { startAt, maxResults, total, count, isLast, values } where total is the overall number of results on the server.

Create a NEW execution (test result) for a test case that is already an item of a test run (test cycle). Appends a new result to the item's execution history — to amend the latest result instead, use update_last_test_result. This tool CANNOT add a test case to a run: the run's item list is fixed when the run is created, and the call fails if the case is not among the run's items. Only the fields you pass are sent. Default statuses: 'Not Executed', 'In Progress', 'Pass', 'Fail', 'Blocked' — case-sensitive internal names; instances may define custom ones. Durations (executionTime) are in milliseconds; dates are ISO 8601. scriptResults record per-step outcomes for STEP_BY_STEP scripts as { index (0-based), status, comment? }. If the same test case is included in the run as several items, disambiguate with matchEnvironment / matchUserKey. Returns { id } of the created result.

Update the LAST (most recent) test result of a run item. Partial update: ONLY the fields you pass are changed, everything else is preserved — do not send fields you do not want to modify. Older executions cannot be targeted; to record a new execution use create_test_result. The test case must already be one of the run's items (the run's composition is fixed at creation). Default statuses: 'Not Executed', 'In Progress', 'Pass', 'Fail', 'Blocked' — case-sensitive internal names; instances may define custom ones. Durations (executionTime) are in milliseconds; dates are ISO 8601. scriptResults record per-step outcomes as { index (0-based), status, comment? }. If the same test case is included in the run as several items, disambiguate with matchEnvironment / matchUserKey.

Create NEW executions (test results) for several test cases of one test run in a single call. Every element's testCaseKey must already be one of the run's items — the run's item list is fixed when the run is created and this tool cannot extend it. In each element only the fields you pass are sent. Default statuses: 'Not Executed', 'In Progress', 'Pass', 'Fail', 'Blocked' — case-sensitive internal names; instances may define custom ones. Durations (executionTime) are in milliseconds; dates are ISO 8601. scriptResults record per-step outcomes as { index (0-based), status, comment? }. matchEnvironment / matchUserKey apply to the whole batch and disambiguate run items when the same test case is included in the run several times. Returns the array of created result ids.

Get the latest (most recent) execution result of a test case across ALL test runs (cycles). Use get_test_run_results to read the results of one specific run instead.

List Zephyr Scale environments configured for a Jira project. Environment names are case-sensitive and are referenced by name in test run items and test results.

Create a Zephyr Scale environment in a Jira project. The name must be unique within the project.

Search Jira users by username, display name or e-mail. Use it to resolve the Jira user key (e.g. 'JIRAUSER10000') required by the owner / executedBy / assignedTo fields of other tools.

Check connectivity and credentials: calls Jira /rest/api/2/myself and, when a default project key is configured, verifies that the Zephyr Scale plugin answers at /rest/atm/1.0.