Settings

The settings endpoint allows you to check and update result statuses.

Result Status

Each test case result is assigned a status based on the outcome of its execution. QA Sphere supports two categories of statuses:

1. Default Statuses: These are the commonly used statuses that come by default. They include passed, failed, blocked, skipped, and open. These statuses cannot be removed or modified.
2. Custom Statuses: If additional statuses are needed, QA Sphere allows for the creation of up to four custom statuses. The labels and colors for these custom statuses can be configured and will be displayed in the UI. In the API, these statuses are referred to as custom1, custom2, custom3, and custom4.

Get Statuses

GET/api/public/v0/settings/preferences/status

Get current status configuration.

Authentication

Requires an API key with at least Viewer role permissions. See Authentication for more details.

Response

Status: 200 OK

{
  statuses: Array<{
    id: string          // Unique identifier for the status ("passed" | "failed" | "blocked" | "skipped" | "open" | "custom1" | "custom2" | "custom3" | "custom4")
    name: string        // Display name of the status
    color: string       // Display color of the status ("blue" | "gray" | "red" | "orange" | "yellow" | "green" | "teal" | "indigo" | "purple" | "pink")
    isDefault: boolean  // Is this a default status
    isActive: boolean   // Is this (custom) status enabled (always true for default statuses)
    inUse: boolean      // Is this (custom) status in use (always true for default statuses)
  }>
}

Example Request

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

Example Response

{
  "statuses": [
    {
      "id": "open",
      "name": "Open",
      "color": "blue",
      "isDefault": true,
      "isActive": true,
      "inUse": true
    },
    {
      "id": "passed",
      "name": "Passed",
      "color": "green",
      "isDefault": true,
      "isActive": true,
      "inUse": true
    },
    {
      "id": "failed",
      "name": "Failed",
      "color": "red",
      "isDefault": true,
      "isActive": true,
      "inUse": true
    },
    {
      "id": "skipped",
      "name": "Skipped",
      "color": "gray",
      "isDefault": true,
      "isActive": true,
      "inUse": true
    },
    {
      "id": "blocked",
      "name": "Blocked",
      "color": "orange",
      "isDefault": true,
      "isActive": true,
      "inUse": true
    },
    {
      "id": "custom1",
      "name": "Known Issue",
      "color": "teal",
      "isDefault": false,
      "isActive": true,
      "inUse": true
    },
    {
      "id": "custom2",
      "name": "Retest",
      "color": "orange",
      "isDefault": false,
      "isActive": false,
      "inUse": false
    },
    {
      "id": "custom3",
      "name": "Custom 3",
      "color": "purple",
      "isDefault": false,
      "isActive": true,
      "inUse": true
    },
    {
      "id": "custom4",
      "name": "Custom 4",
      "color": "teal",
      "isDefault": false,
      "isActive": false,
      "inUse": false
    }
  ]
}

Error Responses

Status Code	Description
401	Invalid or missing API key
403	Insufficient permissions or suspended tenant
500	Internal server error while fetching statuses

Update Custom Statuses

POST/api/public/v0/settings/preferences/status

Update custom statuses.

• Custom statuses apply across the entire account, and any updates will also be reflected in previously added results.
• Once a custom status is enabled and is in use, it cannot be disabled.

Authentication

Requires an API key with at least Admin role permissions. See Authentication for more details.

Request Body

{
  statuses: Array<{
    id: string          // Unique identifier for the custom status ("custom1" | "custom2" | "custom3" | "custom4")
    name: string        // Display name of the status
    color: string       // Display color of the status ("blue" | "gray" | "red" | "orange" | "yellow" | "green" | "teal" | "indigo" | "purple" | "pink")
    isActive: boolean   // Is this custom status enabled
  }>
}

Response

Status: 200 OK

{
  message: "Statuses updated"
}

Example Request

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  -H "Content-Type: application/json" \
  -d '{
    "statuses": [
      {
        "id": "custom3",
        "name": "Blocker",
        "color": "red",
        "isActive": true
      }
    ]
  }' \
  https://your-company.your-region-code.qasphere.com/api/public/v0/settings/preferences/status

Error Responses

Status Code	Description
400	Invalid status id or color
401	Invalid or missing API key
403	Insufficient permissions or suspended tenant
409	Trying to update default or in use custom status
500	Internal server error while updating statuses

important

• Custom statuses can only be updated by users with owner or admin roles.
• Custom statuses apply across the entire account, and any updates will also be reflected in previously added results.
• Once a custom status is enabled and used, it cannot be disabled.