# Test plans API Source: https://docs.qualflare.com/docs/api/test-plans ยท Last updated: 2026-11-03 List and read the test plans of a Qualflare project and the test cases each one selects over the REST API, with paging, sorting and every field. The Test plans API lets you list and read test plans and the cases they select in a Qualflare project over REST at `https://api.qualflare.com/api/v1/test-plans`, authenticated with a project access token. | | | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Base path** | `/api/v1/test-plans` and `/api/v1/test-plan/{seq}` | | **Reads** | Any token. Token creator: (requires the Viewer role or higher in the project). The API has no test plan writes | | **Pages** | 10 plans per page, as `items` and `paging`; a plan's cases come back whole | | **Limits** | [Rate limits and request sizes](https://docs.qualflare.com/docs/api/limits) | | **Errors** | [Errors and status codes](https://docs.qualflare.com/docs/api/errors) | | **CLI** | `qf plans list`, `qf plan get `, `qf plan cases ` ([Plans commands](https://docs.qualflare.com/docs/cli/read-commands#plans)) | | **MCP** | `list_test_plans`, `get_test_plan`, `list_test_plan_cases` ([MCP server reference](https://docs.qualflare.com/docs/api/mcp-reference)) | The three endpoints, each with its own section below: | Endpoint | What it does | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | **GET** `/api/v1/test-plans` | [List test plans](https://docs.qualflare.com/docs/api/test-plans#list-test-plans) | | **GET** `/api/v1/test-plan/{seq}` | [Get a test plan](https://docs.qualflare.com/docs/api/test-plans#get-test-plan) | | **GET** `/api/v1/test-plan/{seq}/cases` | [List a test plan's cases](https://docs.qualflare.com/docs/api/test-plans#list-test-plan-cases) | ## List test plans List test plans returns one page of the project's test plans, searched by name. **GET** `/api/v1/test-plans` Needs a project access token whose creator has the Viewer role or higher in the project. | Name | Type | Default | Required | Description | | --------- | ---------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------- | | `q` | `query`, string | | No | Text to look for in plan names, up to 255 characters | | `page` | `query`, integer | `1` | No | Page number, 1 to 1,000 | | `sortBy` | `query`, string | `seq` | No | `seq`, `name` or `description`. `createdAt` and `updatedAt` are accepted but leave the list unordered | | `sortDir` | `query`, boolean | `false` | No | `true` sorts in descending order | ```bash curl -sS "https://api.qualflare.com/api/v1/test-plans" \ -H "Authorization: Bearer $QF_TOKEN" ``` Returns `200`: A page of test plans: `items` and `paging`, 10 plans per page. * `sortBy` takes `seq`, `name` or `description`. `createdAt` and `updatedAt` are accepted but leave the list unordered. ## Get a test plan Get a test plan returns one plan by its number and adds `caseSeq`, the numbers of the cases you picked, and `querySeq`, the numbers of its saved queries. **GET** `/api/v1/test-plan/{seq}` Needs a project access token whose creator has the Viewer role or higher in the project. | Name | Type | Default | Required | Description | | ----- | --------------- | ------- | -------- | -------------------- | | `seq` | `path`, integer | | Yes | The test plan number | ```bash curl -sS "https://api.qualflare.com/api/v1/test-plan/5" \ -H "Authorization: Bearer $QF_TOKEN" ``` Returns `200`: The test plan, with `caseSeq` and `querySeq`. ```json { "seq": 5, "name": "v2.4 regression", "description": "Cases to run by hand before the v2.4 release", "caseSeq": [ 101, 102, 115 ], "querySeq": [ 2 ], "createdAt": "2026-10-02T11:20:00Z", "updatedAt": "2026-10-27T15:48:19Z" } ``` * A number that isn't a test plan of the project answers `404` with `test plan not found`. ## List a test plan's cases List a test plan's cases returns an array of [cases](https://docs.qualflare.com/docs/api/cases#case-fields), every case of the plan, with no pages. **GET** `/api/v1/test-plan/{seq}/cases` Needs a project access token whose creator has the Viewer role or higher in the project. | Name | Type | Default | Required | Description | | ----- | --------------- | ------- | -------- | -------------------- | | `seq` | `path`, integer | | Yes | The test plan number | ```bash curl -sS "https://api.qualflare.com/api/v1/test-plan/5/cases" \ -H "Authorization: Bearer $QF_TOKEN" ``` Returns `200`: An array of every case of the plan, with no pages. * `isFlaky` is always `false` and `flakyScore` always `0` in this list; [Get a case](https://docs.qualflare.com/docs/api/cases#get-case) has the real values. ## Test plan fields Each test plan in [List test plans](https://docs.qualflare.com/docs/api/test-plans#list-test-plans) has these fields, and [Get a test plan](https://docs.qualflare.com/docs/api/test-plans#get-test-plan) adds `caseSeq` and `querySeq`: | Field | Type | Notes | | ------------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `seq` | integer | The test plan number in the project | | `name` | string | The plan name | | `description` | string | Empty when the plan has none | | `caseSeq` | array of integers | On get only: the numbers of the cases picked for the plan | | `querySeq` | array of integers | On get only: the numbers of the [saved queries](https://docs.qualflare.com/docs/test-management/test-plans#dynamic-queries-tab) attached to the plan | | `createdAt`, `updatedAt` | string | RFC 3339 timestamps | ## CLI and MCP equivalents The qf CLI and the MCP server run the same reads, so they return the same JSON: | REST | qf command and MCP tool | | --------------------------------------- | ---------------------------------------------------------- | | **GET** `/api/v1/test-plans` | `qf plans list`; `list_test_plans` | | **GET** `/api/v1/test-plan/{seq}` | `qf plan get `; `get_test_plan` | | **GET** `/api/v1/test-plan/{seq}/cases` | `qf plan cases `; `list_test_plan_cases` | ## Related * **Guides:** [Test plans](https://docs.qualflare.com/docs/test-management/test-plans) * **Reference:** [Cases and steps API](https://docs.qualflare.com/docs/api/cases) * **CLI/API:** [Qualflare API](https://docs.qualflare.com/docs/api)