# Suites API Source: https://docs.qualflare.com/docs/api/suites · Last updated: 2026-11-03 List and read the test suites of a Qualflare project over the REST API, analyze a suite's coverage and save its score, with every parameter and field. The Suites API lets you list and read test suites, and analyze and save their coverage score, in a Qualflare project over REST at `https://api.qualflare.com/api/v1/suites`, authenticated with a project access token. | | | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Base path** | `/api/v1/suites` and `/api/v1/suite/{suiteSeq}` | | **Reads** | Any token. Token creator: (requires the Viewer role or higher in the project) | | **Writes** | Saving a coverage score: a token created with **Allow writes**. Token creator: (requires the Editor role or higher in the project) | | **Pages** | 20 suites per page, as `items` and `paging` | | **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 suites list`, `qf suite get ` ([Suites commands](https://docs.qualflare.com/docs/cli/read-commands#suites)) | | **MCP** | `list_test_suites`, `get_test_suite`, `analyze_suite_coverage`, `attach_coverage_score` ([MCP server reference](https://docs.qualflare.com/docs/api/mcp-reference)) | The four endpoints, each with its own section below: | Endpoint | What it does | | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | **GET** `/api/v1/suites` | [List suites](https://docs.qualflare.com/docs/api/suites#list-suites) | | **GET** `/api/v1/suite/{suiteSeq}` | [Get a suite](https://docs.qualflare.com/docs/api/suites#get-suite) | | **GET** `/api/v1/suite/{suiteSeq}/coverage-analysis` | [Analyze a suite's coverage](https://docs.qualflare.com/docs/api/suites#analyze-coverage) | | **PUT** `/api/v1/suite/{suiteSeq}/coverage-score` | [Save a coverage score](https://docs.qualflare.com/docs/api/suites#attach-coverage-score) | ## List suites List suites returns one page of the project's test suites, searched and sorted as you ask. **GET** `/api/v1/suites` Needs a project access token whose creator has the Viewer role or higher in the project. | Name | Type | Default | Required | Description | | --------- | ---------------- | ------- | -------- | ----------------------------------------------------------------------------------------------- | | `page` | `query`, integer | `1` | No | Page number, 1 to 1,000 | | `q` | `query`, string | | No | Text to look for in suite names and descriptions, up to 255 characters | | `sortBy` | `query`, string | | No | `seq`, `name`, `priority`, `createdAt`, `updatedAt`, `caseCount`, `teamName` or `coverageScore` | | `sortDir` | `query`, boolean | `false` | No | `true` sorts in descending order | ```bash curl -sS "https://api.qualflare.com/api/v1/suites?page=1" \ -H "Authorization: Bearer $QF_TOKEN" ``` Returns `200`: A page of suites: `items` and `paging`, 20 suites per page. ## Get a suite Get a suite returns one suite by its number. **GET** `/api/v1/suite/{suiteSeq}` Needs a project access token whose creator has the Viewer role or higher in the project. | Name | Type | Default | Required | Description | | ---------- | --------------- | ------- | -------- | ---------------- | | `suiteSeq` | `path`, integer | | Yes | The suite number | ```bash curl -sS "https://api.qualflare.com/api/v1/suite/12" \ -H "Authorization: Bearer $QF_TOKEN" ``` Returns `200`: The suite. ```json { "seq": 12, "name": "Checkout", "description": "Cart, coupons and payment", "priority": "high", "automation": "automated", "testType": "playwright", "coverageScore": 82, "caseCount": 48, "teamSeq": 2, "teamName": "Payments", "isArchived": false, "createdAt": "2026-08-03T10:15:00Z", "updatedAt": "2026-10-28T14:02:41Z" } ``` * A number that isn't a suite of the project answers `404` with `suite not found`. ## Analyze a suite's coverage Analyze a suite's coverage scores the suite's test cases by test type, priority, quality and completeness, and returns the score with recommendations. **GET** `/api/v1/suite/{suiteSeq}/coverage-analysis` Needs a project access token whose creator has the Viewer role or higher in the project. | Name | Type | Default | Required | Description | | ---------- | --------------- | ------- | -------- | ---------------- | | `suiteSeq` | `path`, integer | | Yes | The suite number | ```bash curl -sS "https://api.qualflare.com/api/v1/suite/12/coverage-analysis" \ -H "Authorization: Bearer $QF_TOKEN" ``` Returns `200`: The coverage analysis. Nothing is saved. * It saves nothing, and each call counts toward your plan's monthly coverage analyses (available on Starter, Core, Scale, Enterprise, Open Source); at the quota it answers `402` with `Coverage Analysis quota exceeded (/)`. * Any reader can run it; `canAttachScore` says whether your token may save the score. ## Save a coverage score Save a coverage score stores a 0 to 100 [coverage score](https://docs.qualflare.com/docs/reference/glossary#coverage-score) on the suite. **PUT** `/api/v1/suite/{suiteSeq}/coverage-score` Needs a project access token created with Allow writes, whose creator has the Editor role or higher in the project. | Name | Type | Default | Required | Description | | --------------- | --------------- | ------- | -------- | ----------------------------------------------- | | `suiteSeq` | `path`, integer | | Yes | The suite number | | `coverageScore` | `body`, integer | | Yes | The score to save, 0 to 100; 0 is a valid score | | `reason` | `body`, string | | No | Why the score changed, up to 512 characters | ```bash curl -sS -X PUT "https://api.qualflare.com/api/v1/suite/12/coverage-score" \ -H "Authorization: Bearer $QF_TOKEN" \ -H "Content-Type: application/json" \ -d '{"coverageScore": 82, "reason": "Checked after the release"}' ``` Returns `200`: The updated suite. * `coverageScore` is required, 0 to 100 (0 is a valid score); `reason` is optional, up to 512 characters. * It is not counted against the coverage quota, and it is recorded in the suite's coverage history. ## Suite fields Every suite the Suites API returns has these fields, in list items and in [Get a suite](https://docs.qualflare.com/docs/api/suites#get-suite): | Field | Type | Notes | | ------------------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `seq` | integer | The suite number in the project | | `name` | string | The suite name | | `description` | string | Empty when the suite has none | | `priority` | string | `low`, `medium`, `high` or `critical` | | `automation` | string | `manual` or `automated` | | `testType` | string | The kind of test, or the framework that reported it: a value of `testType` in [List a suite's cases](https://docs.qualflare.com/docs/api/cases#list-suite-cases) | | `coverageScore` | integer | 0 to 100 | | `caseCount` | integer | The number of cases in the suite | | `teamSeq`, `teamName` | integer, string | The owning team, or `null` | | `isArchived` | boolean | `true` for an archived suite | | `archivedAt` | string | When it was archived; left out unless archived | | `createdAt`, `updatedAt` | string | RFC 3339 timestamps | ## Coverage analysis fields The answer of [Analyze a suite's coverage](https://docs.qualflare.com/docs/api/suites#analyze-coverage) has these fields: | Field | Type | Notes | | ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | | `suiteSeq`, `suiteName` | integer, string | The suite | | `testType` | string | The suite's test type | | `totalCases` | integer | The number of cases scored | | `finalScore` | integer | The coverage score | | `breakdown` | object | The four parts of the score: `testTypeScore`, `priorityScore`, `qualityScore` and `completenessScore` | | `analysisSummary` | string | A summary written from the numbers | | `recommendations` | array of strings | Never `null`; empty when there is nothing to add | | `canAttachScore` | boolean | Whether your token may [save the score](https://docs.qualflare.com/docs/api/suites#attach-coverage-score) | | `algorithmVersion` | string | The version of the scoring that produced the numbers | ## CLI and MCP equivalents The qf CLI and the MCP server run the same reads, and the MCP server the same write, so they return the same JSON: | REST | qf command and MCP tool | | ---------------------------------------------------- | --------------------------------------------------- | | **GET** `/api/v1/suites` | `qf suites list`; `list_test_suites` | | **GET** `/api/v1/suite/{suiteSeq}` | `qf suite get `; `get_test_suite` | | **GET** `/api/v1/suite/{suiteSeq}/coverage-analysis` | No qf command; `analyze_suite_coverage` | | **PUT** `/api/v1/suite/{suiteSeq}/coverage-score` | No qf command; `attach_coverage_score` | ## Related * **Guides:** [Test suites and Browse](https://docs.qualflare.com/docs/test-management/test-suites) * **Reference:** [Cases and steps API](https://docs.qualflare.com/docs/api/cases) · [Errors and status codes](https://docs.qualflare.com/docs/api/errors) * **CLI/API:** [Qualflare API](https://docs.qualflare.com/docs/api) · [MCP server reference](https://docs.qualflare.com/docs/api/mcp-reference)