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

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