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:

1. Text: A descriptive label for the requirement (1-255 characters)
2. 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.

tip

• 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

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

tip

• 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": ""
    }
  ]
}