Projects

The projects endpoint allows you to retrieve projects in your account.

Authentication

Project visibility will depend if the user has proper access to the project. If you are the owner or an admin, you may grant access to users to a project by going to your QA Sphere account, then go to the Members page in settings to grant access to the user.

List Projects

GET/api/public/v0/project/paginated

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

Returns a list of all projects.

Query Parameters

Parameter	Type	Description	Default	Example
`archived`	bool	Filter projects by archived state.	No filter	`archived=false`
`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: `code`, `title`, `created_at`, or `updated_at`.	`title`	`sortField=title`
`sortOrder`	string	Sort direction for `sortField`: `asc` or `desc`.	`asc`	`sortOrder=asc`

Response

Status: 200 OK

{
  total: number,               // Total number of projects
  offset: number,              // The page offset
  limit: number,               // The page limit
  data: Array<{                // List of projects in the page
    id: string                 //   Unique identifier for the project
    code: string               //   User specified unique identifier for the project
    title: string              //   Name of the project
    description: html          //   Description of the project (Deprecated: use overviewDescription)
    overviewTitle: string      //   Overview title shown in overview page of the project
    overviewDescription: html  //   Overview description shown in overview page of the project
    links: Array<{             //   A list of links that is shown in the overview page of the project
      url: string              //     URL of the link
      text: string             //     Displayed text of the link
    }>
    createdAt: Date            //   Date when the project is created
    updatedAt: Date            //   Date when project information was last updated
    archivedAt: Date | null    //   Date when the project has been archived
  }>
}

Example Request

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

Example Response

{
  "total": 1,
  "offset": 0,
  "limit": 100,
  "data": [
    {
      "id": "1CJo8oDjj_vkGo2rQAdzz4F",
      "code": "BD",
      "title": "Bistro Delivery",
      "description": "<p>Welcome to the <strong>Bistro Delivery</strong> example project. This project showcases a typical food ordering website with features like a menu, shopping cart, and order process. We've included basic test cases, organized by type, tags, and priorities, along with test runs to demonstrate how QA Sphere can streamline your testing workflow.</p>",
      "overviewTitle": "Bistro Delivery - Example",
      "overviewDescription": "<p>Welcome to the <strong>Bistro Delivery</strong> example project. This project showcases a typical food ordering website with features like a menu, shopping cart, and order process. We've included basic test cases, organized by type, tags, and priorities, along with test runs to demonstrate how QA Sphere can streamline your testing workflow.</p>",
      "links": [
        {
          "text": "Bistro Delivery Site",
          "url": "https://hypersequent.github.io/bistro/"
        },
        {
          "text": "Automation Tests",
          "url": "https://github.com/Hypersequent/bistro-e2e"
        },
        {
          "text": "QA Sphere CLI Tool",
          "url": "https://github.com/Hypersequent/qas-cli"
        }
      ],
      "createdAt": "2025-01-02T11:41:19.547371+04:00",
      "updatedAt": "2025-01-02T11:41:19.547371+04:00",
      "archivedAt": null
    }
  ]
}

Error Responses

Status Code	Description
500	Internal server error during project listing

List Projects (Deprecated)

Deprecated

This endpoint is deprecated. Use List Projects (GET /api/public/v0/project/paginated) instead.

GET/api/public/v0/project

Returns a list of all projects.

Response

Status: 200 OK

{
  projects: Array<{
    // A list of projects
    id: string //   Unique identifier for the project
    code: string //   User specified unique identifier for the project
    title: string //   Name of the project
    description: html //   Description of the project (Deprecated: use overviewDescription)
    overviewTitle: string //   Overview title shown in overview page of the project
    overviewDescription: html //   Overview description shown in overview page of the project
    links: Array<{
      //   A list of links that is shown in the overview page of the project
      url: string //     URL of the link
      text: string //     Displayed text of the link
    }>
    createdAt: Date //   Date when the project is created
    updatedAt: Date //   Date when project information was last updated
    archivedAt: Date | null //   Date when the project has been archived
  }>
}

Example Request

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

Example Response

{
  "projects": [
    {
      "id": "1CJo8oDjj_vkGo2rQAdzz4F",
      "code": "BD",
      "title": "Bistro Delivery",
      "description": "<p>Welcome to the <strong>Bistro Delivery</strong> example project. This project showcases a typical food ordering website with features like a menu, shopping cart, and order process. We've included basic test cases, organized by type, tags, and priorities, along with test runs to demonstrate how QA Sphere can streamline your testing workflow.</p>",
      "overviewTitle": "Bistro Delivery - Example",
      "overviewDescription": "<p>Welcome to the <strong>Bistro Delivery</strong> example project. This project showcases a typical food ordering website with features like a menu, shopping cart, and order process. We've included basic test cases, organized by type, tags, and priorities, along with test runs to demonstrate how QA Sphere can streamline your testing workflow.</p>",
      "links": [
        {
          "text": "Bistro Delivery Site",
          "url": "https://hypersequent.github.io/bistro/"
        },
        {
          "text": "Automation Tests",
          "url": "https://github.com/Hypersequent/bistro-e2e"
        },
        {
          "text": "QA Sphere CLI Tool",
          "url": "https://github.com/Hypersequent/qas-cli"
        }
      ],
      "createdAt": "2025-01-02T11:41:19.547371+04:00",
      "updatedAt": "2025-01-02T11:41:19.547371+04:00",
      "archivedAt": null
    }
  ]
}

Error Responses

Status Code	Description
500	Internal server error during project listing

Get Project

GET/api/public/v0/project/{project_code_or_id}

Returns the project identified by code or id.

Response

Status: 200 OK

{
  id: string // Unique identifier for the project
  code: string // User specified unique identifier for the project
  title: string // Name of the project
  description: html // Description of the project (Deprecated: use overviewDescription)
  overviewTitle: string // Overview title shown in overview page of the project
  overviewDescription: html // Overview description shown in overview page of the project
  links: Array<{
    // A list of links that is shown in the overview page of the project
    url: string //   URL of the link
    text: string //   Displayed text of the link
  }>
  createdAt: Date // Date when the project is created
  updatedAt: Date // Date when project information was last updated
  archivedAt: Date | null // Date when the project has been archived
}

Example Request

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

Example Response

{
  "id": "1CJo8oDjj_vkGo2rQAdzz4F",
  "code": "BD",
  "title": "Bistro Delivery",
  "description": "<p>Welcome to the <strong>Bistro Delivery</strong> example project. This project showcases a typical food ordering website with features like a menu, shopping cart, and order process. We've included basic test cases, organized by type, tags, and priorities, along with test runs to demonstrate how QA Sphere can streamline your testing workflow.</p>",
  "overviewTitle": "Bistro Delivery - Example",
  "overviewDescription": "<p>Welcome to the <strong>Bistro Delivery</strong> example project. This project showcases a typical food ordering website with features like a menu, shopping cart, and order process. We've included basic test cases, organized by type, tags, and priorities, along with test runs to demonstrate how QA Sphere can streamline your testing workflow.</p>",
  "links": [
    {
      "text": "Bistro Delivery Site",
      "url": "https://hypersequent.github.io/bistro/"
    },
    {
      "text": "Automation Tests",
      "url": "https://github.com/Hypersequent/bistro-e2e"
    },
    {
      "text": "QA Sphere CLI Tool",
      "url": "https://github.com/Hypersequent/qas-cli"
    }
  ],
  "createdAt": "2025-01-02T11:41:19.547371+04:00",
  "updatedAt": "2025-01-02T11:41:19.547371+04:00",
  "archivedAt": null
}

Error Responses

Status Code	Description
403	User has no permission to access project
404	Project not found
500	Internal server error during project fetching

Create Project

POST/api/public/v0/project

Creates a new project. Only users with role Admin or Owner are allowed to create a project.

Request Body

{
  code: string                // Unique project code (2-5 alphanumeric characters)
  title: string               // Name of the project (max 255 characters)
  links?: Array<{             // Optional list of links for the project overview
    url: string               //   URL of the link (max 255 characters)
    text: string              //   Displayed text of the link (max 255 characters)
  }>
  overviewTitle?: string      // Optional overview title (max 255 characters)
  overviewDescription?: html  // Optional overview description
}

Example Request

curl -X POST \
  -H "Authorization: ApiKey your.api.key.here" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "BD",
    "title": "Bistro Delivery",
    "links": [
      {"url": "https://hypersequent.github.io/bistro/", "text": "Bistro Delivery Site"},
      {"url": "https://github.com/Hypersequent/bistro-e2e", "text": "Automation Tests"}
    ],
    "overviewTitle": "Bistro Delivery - Example",
    "overviewDescription": "<p>Welcome to the <strong>Bistro Delivery</strong> example project. This project showcases a typical food ordering website with features like a menu, shopping cart, and order process.</p>"
  }' \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project

Response Fields

{
  id: string // Unique identifier for the project
}

Example Response

Status: 201 Created

{
  "id": "1CJo8oDjj_vkGo2rQAdzz4F"
}

Error Responses

Status Code	Description
400	Invalid project code format
403	User does not have admin permission
409	Project with the same title already exists
500	Internal server error during project creation

Projects

AuthenticationCopy Anchor Link

List ProjectsCopy Anchor Link

Query ParametersCopy Anchor Link

ResponseCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

Error ResponsesCopy Anchor Link

List Projects (Deprecated)Copy Anchor Link

ResponseCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

Error ResponsesCopy Anchor Link

Get ProjectCopy Anchor Link

ResponseCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

Error ResponsesCopy Anchor Link

Create ProjectCopy Anchor Link

Request BodyCopy Anchor Link

Example RequestCopy Anchor Link

Response FieldsCopy Anchor Link

Example ResponseCopy Anchor Link

Error ResponsesCopy Anchor Link

On this page

Authentication

List Projects

Query Parameters

Response

Example Request

Example Response

Error Responses

List Projects (Deprecated)

Response

Example Request

Example Response

Error Responses

Get Project

Response

Example Request

Example Response

Error Responses

Create Project

Request Body

Example Request

Response Fields

Example Response

Error Responses