Public API

The qasphere api command exposes the full QA Sphere public API as terminal commands. Every command prints JSON to stdout (errors to stderr) for clean piping into jq, scripts, and CI pipelines.

qasphere api <resource> <action> [options]

Exit code is 0 on success, 1 on failure. Pass -h to any subcommand for its full signature, options, examples, and a link to the matching REST endpoint reference.

Command tree

qasphere api
├── audit-logs
│   └── list                                    # List audit log entries
├── custom-fields
│   └── list --project-code                     # List custom fields
├── files
│   └── upload --file                           # Upload a file attachment
├── folders
│   ├── list --project-code                     # List folders
│   └── bulk-create --project-code --folders    # Create/update folders
├── milestones
│   ├── list --project-code                     # List milestones
│   └── create --project-code --title           # Create milestone
├── projects
│   ├── list                                    # List all projects
│   ├── get --project-code                      # Get project by code
│   └── create --code --title                   # Create project
├── requirements
│   └── list --project-code                     # List requirements
├── results
│   ├── create --project-code --run-id --tcase-id --status  # Create result
│   └── batch-create --project-code --run-id --items        # Batch create results
├── runs
│   ├── create --project-code --title --type --query-plans  # Create run
│   ├── list --project-code                     # List runs
│   ├── clone --project-code --run-id --title   # Clone run
│   ├── close --project-code --run-id           # Close run
│   ├── test-cases
│   │   ├── list --project-code --run-id        # List test cases in run
│   │   └── get --project-code --run-id --tcase-id  # Get test case in run
│   └── logs
│       └── create --project-code --run-id --comment  # Create run log
├── settings
│   ├── list-statuses                           # List result statuses
│   └── update-statuses --statuses              # Update custom statuses
├── shared-preconditions
│   ├── list --project-code                     # List shared preconditions
│   └── get --project-code --id                 # Get shared precondition
├── shared-steps
│   ├── list --project-code                     # List shared steps
│   └── get --project-code --id                 # Get shared step
├── tags
│   └── list --project-code                     # List tags
├── test-cases
│   ├── list --project-code                     # List test cases
│   ├── get --project-code --tcase-id           # Get test case
│   ├── count --project-code                    # Count test cases
│   ├── create --project-code --body            # Create test case
│   └── update --project-code --tcase-id --body # Update test case
├── test-plans
│   └── create --project-code --body            # Create test plan
└── users
    └── list                                    # List all users

files upload

qasphere api files upload --file ... uses the public batch upload endpoint internally and returns the first uploaded file from that response.

For per-endpoint request/response details, see the REST API Endpoints reference.

Pagination

List commands support pagination via:

• --page <n> and --limit <n> — offset-based pagination
• --sort-field <name> and --sort-order <asc|desc> — sorting (where supported)

audit-logs list uses cursor-based pagination instead:

• --after <cursor> — continuation cursor from the previous page
• --count <n> — page size

Passing JSON bodies

Commands that mutate complex resources (runs create, test-cases create/update, test-plans create, results create/batch-create, folders bulk-create, settings update-statuses) accept their payload three ways:

• --body '<json>' — inline JSON string
• --body-file <path> — path to a JSON file
• Individual field flags — e.g. --title, --status, --comment

Field flags merge into --body / --body-file with field flags taking precedence. The combined body must always be valid JSON.

Workflow examples

The examples below assume QAS_TOKEN and QAS_URL are configured (see Auth) and use jq for JSON parsing.

1. Open a run, post results, and close it

Useful when results come from a tool that doesn't produce JUnit/Playwright/Allure output:

RUN_ID=$(qasphere api runs create --project-code PRJ \
  --title "Smoke $(date +%Y-%m-%d)" --type static \
  --query-plans '[{"tcaseIds": ["abc123", "def456"]}]' | jq -r '.id')

qasphere api results batch-create --project-code PRJ --run-id "$RUN_ID" \
  --items '[{"tcaseId": "abc123", "status": "passed"}, {"tcaseId": "def456", "status": "failed", "comment": "timeout on /cart"}]'

qasphere api runs close --project-code PRJ --run-id "$RUN_ID"

2. Run-progress report

List open runs with their pass/fail/open counts:

qasphere api runs list --project-code PRJ --closed false \
  | jq '.[] | {title, passed: .statusCounts.passed, failed: .statusCounts.failed, open: .statusCounts.open, total: .statusCounts.all}'

3. Pre-create a run, then upload automation results into it

RUN_ID=$(qasphere api runs create --project-code PRJ \
  --title "CI build $BUILD_NUMBER" --type static \
  --query-plans '[{"tcaseIds": ["abc123"]}]' \
  --milestone-id 7 | jq -r '.id')

qasphere junit-upload -r "$QAS_URL/project/PRJ/run/$RUN_ID" ./test-results.xml

4. Bulk-create folders and test cases

qasphere api folders bulk-create \
  --project-code PRJ \
  --folders '[{"path": ["Authentication", "Login"]}, {"path": ["Authentication", "OAuth"]}]'

qasphere api test-cases create \
  --project-code PRJ \
  --body '{"title": "Login with valid credentials", "type": "standalone", "folderId": 1, "priority": "high"}'

Error handling

• Missing credentials — the CLI prints a setup guide to stderr and exits with code 1. See Auth.
• Validation errors — invalid CLI arguments or API validation failures are reported to stderr with the offending option name.
• HTTP errors — formatted and printed to stderr. Use --verbose for full stack traces.