Core concepts

Everything is an object

Everything in your QualGent account is an object. Your uploaded builds correspond to App objects, and your library of reusable test scenarios are TestCase objects. A Category groups related test cases. A Submission is one request for QualGent to run a set of test cases against a build and review the results. A BugReport describes a bug found on a build: its steps, expected and actual results, severity, and evidence.

Objects have lives

Most objects progress through states. A Submission starts as received, moves through testing and verifying, and ends as complete. An App is uploaded once and then referenced by ID across many requests. Retaining these IDs in your CI scripts is the key to building reliable pipelines.

An integration is made out of cooperating objects

A typical CI integration uploads a new build, submits a mission request against that build, and polls the request until it completes. No single endpoint does all three — your integration is the choreography between Apps, Test cases, and Missions.

Key features

The path a mission takes

Here's what happens between the moment you POST a build and the moment verified results come back. A mission request is run and reviewed by QualGent, so the path is longer than a single API call. Knowing each stage makes polling, retries, and failures much easier to reason about.

Quickstart

A typical integration walks three steps:

List all available test cases in your organization with a single request. This is the lightest-weight call you can make — it's a good way to verify your key works before you upload a build.

curl https://api.qualgent.ai/v1/test-cases/list \
  -H "X-Api-Key: qg_your_api_key_here"

import requests

response = requests.get(
    "https://api.qualgent.ai/v1/test-cases/list",
    headers={"X-Api-Key": "qg_your_api_key_here"},
)
print(response.json())

const response = await fetch("https://api.qualgent.ai/v1/test-cases/list", {
  headers: { "X-Api-Key": "qg_your_api_key_here" },
});
console.log(await response.json());

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://api.qualgent.ai/v1/test-cases/list", nil)
    req.Header.Add("X-Api-Key", "qg_your_api_key_here")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

[
  {
    "id": "tc_1234567890",
    "name": "Login Flow Test",
    "status": "active",
    "category": { "id": "cat_abc123", "name": "Smoke Tests" }
  }
]

If everything worked, you'll get a JSON array of your organization's test cases. From here, head to the Requesting runs with missions guide to request runs.

Authentication

export QUALGENT_API_KEY="qg_your_api_key_here"

curl https://api.qualgent.ai/v1/apps/list \
  -H "X-Api-Key: $QUALGENT_API_KEY"

import os, requests
from dotenv import load_dotenv

load_dotenv()
response = requests.get(
    "https://api.qualgent.ai/v1/apps/list",
    headers={"X-Api-Key": os.environ["QUALGENT_API_KEY"]},
)

require("dotenv").config();

const response = await fetch("https://api.qualgent.ai/v1/apps/list", {
  headers: { "X-Api-Key": process.env.QUALGENT_API_KEY },
});

Rate limits

Managing your applications

curl https://api.qualgent.ai/v1/apps/upload \
  -H "X-Api-Key: qg_your_api_key_here" \
  -F "file=@/path/to/your/app.apk" \
  -F "app_name=MyApp" \
  -F "version=1.0.0"

import requests

with open("/path/to/your/app.apk", "rb") as f:
    response = requests.post(
        "https://api.qualgent.ai/v1/apps/upload",
        headers={"X-Api-Key": "qg_your_api_key_here"},
        files={"file": f},
        data={"app_name": "MyApp", "version": "1.0.0"},
    )

app_file_id = response.json()["file"]["id"]

import FormData from "form-data";
import fs from "fs";

const form = new FormData();
form.append("file", fs.createReadStream("/path/to/your/app.apk"));
form.append("app_name", "MyApp");
form.append("version", "1.0.0");

const response = await fetch("https://api.qualgent.ai/v1/apps/upload", {
  method: "POST",
  headers: { "X-Api-Key": "qg_your_api_key_here", ...form.getHeaders() },
  body: form,
});
const { file } = await response.json();

package main

import (
    "bytes"
    "mime/multipart"
    "net/http"
    "os"
    "io"
)

func main() {
    f, _ := os.Open("/path/to/your/app.apk")
    defer f.Close()

    body := &bytes.Buffer{}
    w := multipart.NewWriter(body)
    part, _ := w.CreateFormFile("file", "app.apk")
    io.Copy(part, f)
    w.WriteField("app_name", "MyApp")
    w.WriteField("version", "1.0.0")
    w.Close()

    req, _ := http.NewRequest("POST", "https://api.qualgent.ai/v1/apps/upload", body)
    req.Header.Add("X-Api-Key", "qg_your_api_key_here")
    req.Header.Set("Content-Type", w.FormDataContentType())
    http.DefaultClient.Do(req)
}

{
  "success": true,
  "file": {
    "id": "3f9a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "file_path": "user123/1757339253852-MyApp-1.0.0.apk",
    "filename": "1757339253852-MyApp-1.0.0.apk",
    "original_name": "app.apk",
    "file_size": 52428800,
    "file_type": "application/vnd.android.package-archive",
    "app_name": "MyApp",
    "version": "1.0.0",
    "os": "Android",
    "package_name": "com.example.myapp",
    "user_id": "6f88bc25-2f3e-44ec-9486-dadb388fd4f4",
    "organization_id": "58ecde76-d294-43aa-934b-0142a506b4e9"
  }
}

Handling test cases

Test cases are the reusable scenarios QualGent runs against your builds. List them to find the IDs you submit in a mission request, inspect one in full, or create and update them through the API. To run them, see Requesting runs with missions.

List test cases

Returns every test case in your organization with its category, newest first. Pass category to return only the test cases in one category.

curl "https://api.qualgent.ai/v1/test-cases/list?category=770e8400-e29b-41d4-a716-446655440000" \
  -H "X-Api-Key: qg_your_api_key_here"

import requests

response = requests.get(
    "https://api.qualgent.ai/v1/test-cases/list",
    headers={"X-Api-Key": "qg_your_api_key_here"},
    params={"category": "770e8400-e29b-41d4-a716-446655440000"},
)
for test_case in response.json():
    print(test_case["id"], test_case["name"], test_case["status"])

[
  {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "name": "Login Flow Test",
    "status": "active",
    "category": { "id": "770e8400-e29b-41d4-a716-446655440000", "name": "Smoke Tests" }
  }
]

An organization with no test cases gets an empty object, {}, rather than an empty array.

Get a test case

Returns one test case in full: its steps, expected_result, priority, category, declared variables, attached files, and its version history in versions.

curl https://api.qualgent.ai/v1/test-cases/660e8400-e29b-41d4-a716-446655440000 \
  -H "X-Api-Key: qg_your_api_key_here"

Create a test case

name, steps and expected_result are required. Each step is one action; kind is optional and marks it as setup, act or verify. You can also set priority, description, category_id and variables.

curl https://api.qualgent.ai/v1/test-cases \
  -H "X-Api-Key: qg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Login Flow Test",
    "steps": [
      { "description": "Open the app", "kind": "setup" },
      { "description": "Tap Log In and enter valid credentials", "kind": "act" },
      { "description": "Verify the home screen is shown", "kind": "verify" }
    ],
    "expected_result": "The user lands on the home screen",
    "priority": "High"
  }'

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "name": "Login Flow Test",
  "version_id": "880e8400-e29b-41d4-a716-446655440000",
  "files": [],
  "warnings": null
}

Update a test case

Send only the fields you want to change. Every update creates a new version, and the response returns its version_number and version_id.

curl -X PATCH https://api.qualgent.ai/v1/test-cases/660e8400-e29b-41d4-a716-446655440000 \
  -H "X-Api-Key: qg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "Medium" }'

Requesting runs with missions

A mission request hands a set of test cases and a build to QualGent. It follows the same flow as the Run button in the dashboard: the request is recorded as a Submission, QualGent executes the tests, reviews every result, and reports verified bugs back to you. You don't pick a device; it follows from the build you submit.

Submit a request

curl https://api.qualgent.ai/v1/missions/submit \
  -H "X-Api-Key: qg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "test_case_ids": [
      "660e8400-e29b-41d4-a716-446655440000",
      "660e8400-e29b-41d4-a716-446655440001"
    ],
    "app_file_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

import requests

response = requests.post(
    "https://api.qualgent.ai/v1/missions/submit",
    headers={"X-Api-Key": "qg_your_api_key_here"},
    json={
        "test_case_ids": [
            "660e8400-e29b-41d4-a716-446655440000",
            "660e8400-e29b-41d4-a716-446655440001",
        ],
        "app_file_id": "550e8400-e29b-41d4-a716-446655440000",
    },
)
result = response.json()
print(result["submission_id"], result["submitted"], result["failed"])

{
  "submitted": 2,
  "failed": 0,
  "failures": [],
  "submission_id": "7b0e8400-e29b-41d4-a716-446655440000"
}

A test case that can't be submitted is listed in failures with the reason, and the rest still go ahead. The response is 200 either way, so check failed.

One open request at a time

An organization has one open request at a time. A request stays open until QualGent has published a result for every test case in it. While one is open, POST /v1/missions/submit returns 409 with code: "run_in_progress" and the open request in open_run.

Send "replace_open": true to cancel the open request and start the new one. Replacing removes the earlier request along with any results already recorded on it, so use it only when the earlier request is no longer wanted.

Follow progress

curl "https://api.qualgent.ai/v1/missions/submissions?submission_id=7b0e8400-e29b-41d4-a716-446655440000" \
  -H "X-Api-Key: qg_your_api_key_here"

Each request carries a stage:

progress gives overall, tested and verified as percentages, and minutesLeft estimates the time left in the current stage when it is known. Verified bugs appear in bugs with their id, bugId and summary, and test cases QualGent could not cover appear in notCovered with a note. A request can take hours, so poll on a long interval rather than in a tight loop. To get the steps, severity and evidence of each bug, see Reading bug reports.

Cancel a request

A request can be cancelled while nothing in it has started; canCancel on the request tells you whether that is still the case. After that, the call returns 409. A cancelled request is removed.

curl -X POST https://api.qualgent.ai/v1/missions/submissions/7b0e8400-e29b-41d4-a716-446655440000/cancel \
  -H "X-Api-Key: qg_your_api_key_here"

Reading bug reports

A BugReport is the full write-up of a bug: the steps to reproduce it, what was expected and what happened, its severity, and the screenshot or recording that shows it. The bugs on a mission request carry only an id, bugId and summary. This is where you read the rest.

Bug reports for a build

Pass a build's app_file_id to get every bug report filed against it, most severe first and newest first within a severity. This is a GET request: the build goes in the query string, your API key goes in the X-Api-Key header, and there is no request body.

app_file_id is the build's id, not its version number. It is returned when you upload the build, and GET /v1/apps/list lists the builds you already have.

curl "https://api.qualgent.ai/v1/bug-reports?app_file_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Api-Key: qg_your_api_key_here"

import requests

response = requests.get(
    "https://api.qualgent.ai/v1/bug-reports",
    headers={"X-Api-Key": "qg_your_api_key_here"},
    params={"app_file_id": "550e8400-e29b-41d4-a716-446655440000"},
)
for bug in response.json()["bugs"]:
    print(bug["bugId"], bug["severity"], bug["summary"])

{
  "bugs": [
    {
      "id": "9d0e8400-e29b-41d4-a716-446655440000",
      "bugId": "BUG_014",
      "summary": "Keyboard stays open after leaving the chat screen",
      "steps": "Open the app\nOpen any chat\nTap the message field\nGo back to the chat list",
      "resultDetails": {
        "expected": "The keyboard closes when the chat screen is left.",
        "actual": "The keyboard stays open over the chat list."
      },
      "status": "open",
      "severity": "medium",
      "failureClassification": "app_bug",
      "appFileId": "550e8400-e29b-41d4-a716-446655440000",
      "appFile": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "appName": "MyApp",
        "version": "1.4.2",
        "os": "android",
        "originalName": "myapp-1.4.2.apk"
      },
      "attachment": {
        "name": "keyboard-stays-open.mp4",
        "type": "video/mp4",
        "size": 4816220,
        "downloadUrl": "https://..."
      },
      "externalTicket": {
        "provider": "github",
        "key": "acme/myapp#42",
        "url": "https://github.com/acme/myapp/issues/42"
      },
      "createdAt": "2026-10-02T11:53:44.507649+00:00",
      "updatedAt": "2026-10-02T12:55:22.176645+00:00"
    }
  ]
}

Narrow the result with status, severity and failure_classification. Leave out app_file_id to read bug reports across every build.

The first 100 bug reports are returned. Pass limit, up to 500, to get more in one response, and offset to page through the rest.

steps is a single string with one step per line. resultDetails, appFile, attachment and externalTicket are null when the bug has none.

One bug report

Read a single report by its id, such as the id of a bug listed on a mission request. The response is one bug report in the same shape as above.

curl https://api.qualgent.ai/v1/bug-reports/9d0e8400-e29b-41d4-a716-446655440000 \
  -H "X-Api-Key: qg_your_api_key_here"

What you get back

Results are limited to the organization your API key belongs to.

When a bug appears

QualGent reviews the bugs it finds before publishing them to you. A bug appears here at the moment it appears in bugs on the mission request, and not before. Until then, and after a bug is deleted, GET /v1/bug-reports/{id} returns 404.

Downloading evidence

attachment.downloadUrl is a pre-signed URL that is valid for one hour. Download the file when you read the report instead of storing the URL, and read the report again when you need a fresh one.

Organizing with categories

# 1. Fetch all categories
curl https://api.qualgent.ai/v1/categories/list \
  -H "X-Api-Key: qg_your_api_key_here"

# 2. List only the test cases in a specific category
curl "https://api.qualgent.ai/v1/test-cases/list?category=cat_checkout" \
  -H "X-Api-Key: qg_your_api_key_here"

Using test case variables

{
  "name": "Search and verify result",
  "steps": [
    { "description": "Open the app and tap the search bar" },
    { "description": "Type {{query}} and submit" },
    { "description": "Wait up to {{timeout_seconds}} seconds for results" }
  ],
  "variables": [
    { "name": "query",           "type": "string", "required": true,  "description": "Search term to type" },
    { "name": "timeout_seconds", "type": "number", "required": false, "default": 30 }
  ]
}

CI/CD integration pattern

import os, time, sys, requests

API = "https://api.qualgent.ai/v1"
H = {"X-Api-Key": os.environ["QUALGENT_API_KEY"]}

# 1. Upload build
with open("build/app.apk", "rb") as f:
    up = requests.post(f"{API}/apps/upload", headers=H,
        files={"file": f},
        data={"app_name": "MyApp", "version": os.environ["GITHUB_SHA"][:7]}).json()
app_id = up["file"]["id"]

# 2. Request runs for the smoke set
resp = requests.post(f"{API}/missions/submit", headers=H, json={
    "test_case_ids": os.environ["SMOKE_TEST_IDS"].split(","),
    "app_file_id": app_id,
})
if resp.status_code == 409:
    sys.exit(f"A request is already open: {resp.json()['open_run']['id']}")
resp.raise_for_status()
result = resp.json()
if result["failed"] or not result["submission_id"]:
    sys.exit(f"Not submitted: {result['failures']}")
submission_id = result["submission_id"]

# 3. Poll until every result has been published
while True:
    time.sleep(300)
    poll = requests.get(f"{API}/missions/submissions", headers=H,
        params={"submission_id": submission_id})
    if poll.status_code == 404:
        sys.exit("The request was cancelled or replaced")
    if poll.status_code >= 500:
        continue  # transient; try again on the next interval
    poll.raise_for_status()
    request = poll.json()["requests"][0]
    print(request["stage"], request["progress"])
    if request["stage"] == "complete":
        break

# 4. Report anything not covered, then fail on a cancelled request or a verified bug
for item in request["notCovered"]:
    print(f"Not covered: {item['name']} ({item['note']})")
if request["cancelled"]:
    sys.exit("The request was cancelled")
for bug in request["bugs"]:
    print(f"{bug['bugId']}: {bug['summary']}")
sys.exit(1 if request["bugs"] else 0)

# GitHub Actions step
- name: QualGent smoke tests
  env:
    QUALGENT_API_KEY: ${{ secrets.QUALGENT_API_KEY }}
  run: |
    UP=$(curl -s https://api.qualgent.ai/v1/apps/upload \
      -H "X-Api-Key: $QUALGENT_API_KEY" \
      -F "file=@build/app.apk" -F "app_name=MyApp" -F "version=$GITHUB_SHA")
    APP_ID=$(echo "$UP" | jq -r .file.id)
    echo "app_id=$APP_ID" >> $GITHUB_OUTPUT
    # ... submit & poll omitted for brevity

Errors & retries

Apps

An App represents an uploaded mobile build (APK, IPA, or AAB). Upload once, reference many times.

Test cases

A TestCase is a reusable scenario authored in the QualGent dashboard. The API lets you list them and inspect their metadata; to run them, see Missions. Test cases may declare a variables schema; each variable's key can be referenced inside step text as {{key}} — see Using test case variables.

Missions

A Submission is one request to run test cases against a build. It goes through the same flow as the Run button in the QualGent dashboard: QualGent executes the tests, reviews the results, and reports verified bugs back to you. An organization has one open request at a time.

Bug reports

A BugReport is a bug found on one of your builds, with its steps, expected and actual results, severity, and evidence. A bug found by QualGent appears once QualGent has reviewed it.

Categories

A Category groups related test cases (e.g. "Smoke", "Regression", "Payments"). Use category IDs to filter listings and batch runs.

Error codes

QualGent uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error caused by the request. Codes in the 5xx range indicate an error with QualGent's servers.

HTTP status reference

Example error response body:

{
  "error": "A run is already in progress",
  "code": "run_in_progress",
  "open_run": {
    "id": "7b0e8400-e29b-41d4-a716-446655440000",
    "submitted_at": "2026-10-01T15:00:00.000Z",
    "build": "MyApp 1.4.2"
  }
}

2026

2025