Requirements

The requirements endpoints allow you to retrieve requirements that are linked to test cases within a project. Requirements help track traceability between test cases and external specifications, user stories, or other documentation.

About Requirements

Requirements are references to external documentation or specifications that test cases are designed to verify. They consist of:

Text: A descriptive label for the requirement (1-255 characters)
URL (optional): A link to the external requirement document or issue tracker

Requirements can be linked to multiple test cases, and a single test case can be linked to multiple requirements. This enables full traceability between your tests and the specifications they validate.

Requirements can be linked to external issues when a Jira or Linear integration is configured for the project
Use include=tcaseCount to see how many test cases are linked to each requirement
Requirements without any linked test cases are still returned in the list

List Requirements

GET/api/public/v0/project/{project_id}/requirement/paginated

/paginated endpoints are transitional. In API v1, the base paths will return paginated responses and the /paginated suffix will be removed.

Retrieves all requirements within a project, optionally sorted and with additional fields included.

Path Parameters

project_id: The project identifier (can be either the project code or UUID)

Query Parameters

Parameter	Type	Description	Default	Example
`offset`	number	Number of rows to skip before returning results.	`0`	`offset=10`
`limit`	number	Maximum number of rows to return. Accepted range: 0–1,000.	`100`	`limit=20`
`sortField`	string	Field to sort by: `created_at` or `text`.	`text`	`sortField=text`
`sortOrder`	string	Sort direction for `sortField`: `asc` or `desc`.	`asc`	`sortOrder=asc`
`include`	string	Include additional fields omitted by default. Accepted value: `tcaseCount`.	None	`include=tcaseCount`

Use include=tcaseCount to see how many test cases are linked to each requirement
Sorting by created_at shows the most recently created requirements first (with desc) or oldest first (with asc)
Sorting by text provides alphabetical ordering

Example Request

Fetch all requirements

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/requirement/paginated

Fetch all requirements sorted by text in ascending order

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/requirement/paginated?sortField=text&sortOrder=asc

Fetch all requirements with test case count included

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/requirement/paginated?include=tcaseCount

Response Fields

{
  total: number,             // Total number of requirements
  offset: number,            // The page offset
  limit: number,             // The page limit
  data: Array<{              // List of requirements in the page
    id: string               //   Unique identifier of the requirement (HQID7 format)
    text: string             //   Descriptive label for the requirement
    url: string              //   URL to the external requirement document (empty string if not set)
    integrationLink?: {      //   Integration link (only present if linked to Jira or Linear)
      type: string           //     Integration type ("jira" or "linear")
      integrationId: string  //     ID of the integration configuration
      issueId: string        //     Internal issue ID (Jira numeric ID or Linear UUID)
      issueTitle: string     //     Title of the linked issue
      issueUrl: string       //     Full URL to the linked issue
      remoteLinkId: string   //     Remote link/attachment ID in the external system
    }
    tcaseCount?: number      //   Number of test cases linked to this requirement (only included if requested)
  }>
}

Example Response

{
  "total": 3,
  "offset": 0,
  "limit": 100,
  "data": [
    {
      "id": "1CKgJ5HMU_1VQTDrRJDdDVW",
      "text": "User Authentication",
      "url": "https://docs.example.com/specs/auth",
      "tcaseCount": 5
    },
    {
      "id": "1CKgJ5HMU_2BJje4hdXZHag",
      "text": "PROJ-456: Implement password reset functionality",
      "url": "https://jira.example.com/browse/PROJ-456",
      "integrationLink": {
        "type": "jira",
        "integrationId": "1CTPNLhFU_rPbCr23CbqftL",
        "issueId": "10456",
        "issueTitle": "Implement password reset functionality",
        "issueUrl": "https://jira.example.com/browse/PROJ-456",
        "remoteLinkId": "12345"
      },
      "tcaseCount": 3
    },
    {
      "id": "1CKgJ5HMU_3apSDSQWRw6Ys",
      "text": "Performance Requirements",
      "url": ""
    }
  ]
}

List Requirements (Deprecated)

Deprecated

This endpoint is deprecated. Use List Requirements (GET /api/public/v0/project/{project_id}/requirement/paginated) instead.

GET/api/public/v0/project/{project_id}/requirement

Retrieves all requirements within a project, optionally sorted and with additional fields included.

Path Parameters

project_id: The project identifier (can be either the project code or UUID)

Query Parameters

All query parameters are optional.

Parameter	Type	Description	Allowed Values	Example
`sortField`	string	Field to sort by	`created_at`, `text`	`sortField=text`
`sortOrder`	string	Sort order (requires `sortField`; default: `desc`)	`asc`, `desc`	`sortOrder=asc`
`include`	string	Include additional fields in the response which are omitted by default	`tcaseCount`	`include=tcaseCount`

Use include=tcaseCount to see how many test cases are linked to each requirement
Sorting by created_at shows the most recently created requirements first (with desc) or oldest first (with asc)
Sorting by text provides alphabetical ordering

Example Request

Fetch all requirements

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/requirement

Fetch all requirements sorted by text in ascending order

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/requirement?sortField=text&sortOrder=asc

Fetch all requirements with test case count included

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/requirement?include=tcaseCount

Response Fields

{
  requirements: Array<{
    // List of requirement objects
    id: string // Unique identifier of the requirement (HQID7 format)
    text: string // Descriptive label for the requirement
    url: string // URL to the external requirement document (empty string if not set)
    integrationLink?: {
      // Integration link (only present if linked to Jira or Linear)
      type: string // Integration type ("jira" or "linear")
      integrationId: string // ID of the integration configuration
      issueId: string // Internal issue ID (Jira numeric ID or Linear UUID)
      issueTitle: string // Title of the linked issue
      issueUrl: string // Full URL to the linked issue
      remoteLinkId: string // Remote link/attachment ID in the external system
    }
    tcaseCount?: number // Number of test cases linked to this requirement (only included if requested)
  }>
}

Example Response

{
  "requirements": [
    {
      "id": "1CKgJ5HMU_1VQTDrRJDdDVW",
      "text": "User Authentication",
      "url": "https://docs.example.com/specs/auth",
      "tcaseCount": 5
    },
    {
      "id": "1CKgJ5HMU_2BJje4hdXZHag",
      "text": "PROJ-456: Implement password reset functionality",
      "url": "https://jira.example.com/browse/PROJ-456",
      "integrationLink": {
        "type": "jira",
        "integrationId": "1CTPNLhFU_rPbCr23CbqftL",
        "issueId": "10456",
        "issueTitle": "Implement password reset functionality",
        "issueUrl": "https://jira.example.com/browse/PROJ-456",
        "remoteLinkId": "12345"
      },
      "tcaseCount": 3
    },
    {
      "id": "1CKgJ5HMU_3apSDSQWRw6Ys",
      "text": "Performance Requirements",
      "url": ""
    }
  ]
}

Requirements

About RequirementsCopy Anchor Link

List RequirementsCopy Anchor Link

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

Example RequestCopy Anchor Link

Fetch all requirementsCopy Anchor Link

Fetch all requirements sorted by text in ascending orderCopy Anchor Link

Fetch all requirements with test case count includedCopy Anchor Link

Response FieldsCopy Anchor Link

Example ResponseCopy Anchor Link

List Requirements (Deprecated)Copy Anchor Link

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

Example RequestCopy Anchor Link

Fetch all requirementsCopy Anchor Link

Fetch all requirements sorted by text in ascending orderCopy Anchor Link

Fetch all requirements with test case count includedCopy Anchor Link

Response FieldsCopy Anchor Link

Example ResponseCopy Anchor Link

On this page

About Requirements

List Requirements

Path Parameters

Query Parameters

Example Request

Fetch all requirements

Fetch all requirements sorted by text in ascending order

Fetch all requirements with test case count included

Response Fields

Example Response

List Requirements (Deprecated)

Path Parameters

Query Parameters

Example Request

Fetch all requirements

Fetch all requirements sorted by text in ascending order

Fetch all requirements with test case count included

Response Fields

Example Response