API Access

The QA.army API exposes documented Workspace, Project, Test, and Run operations under the same access rules as the app. Start with these public references:

• Authentication guide: authorize a coding agent through the CLI.
• OpenAPI document: request and response schemas, credential requirements, and errors.
• Test-writing skill: author useful steps and observable expectations.

Use the CLI guide for a terminal workflow that manages authentication without exposing bearer values. Use Coding Agents for a complete Test-authoring example.

Check the operation’s permissions

Authorization depends on both Workspace membership and credential capabilities. After its human claim is completed, a registered agent can discover authorized Workspaces and Projects, manage Test Groups, create and update saved Tests, and create, start, inspect, or cancel Runs. Workspace Owners can also read and update an existing connected GitHub deployment watch. These operations reuse the same claimed identity; they do not require a second API key.

The claim does not grant Test deletion, Test Account metadata or credentials, Live View, membership changes, billing, or integration consent. Provisional registration alone does not grant the claimed identity’s capabilities.

Supported user sessions and profile API keys permit additional operations. Test Account access and API-key management require a signed-in user session. Check the current OpenAPI security requirements for the operation before building an integration. Do not assume a successful login grants every capability.

Keep credentials in an approved credential store or secret manager. Never put them in Test text, URLs, source control, shared receipts, or agent prompts.

Preserve resource IDs and retry intent

Send an Idempotency-Key on mutations that require it. Reuse the same key and identical payload when retrying an uncertain response; use a new key for a deliberately new operation. A timeout does not establish whether a remote operation completed. Read the existing resource before requesting more work.

Test updates use the current version in If-Match. Reload and reconcile a version conflict instead of overwriting another editor’s work. List endpoints can return different collection and pagination shapes; use each operation’s schema and returned continuation fields rather than assuming the first response is a complete inventory.

Read the final result

Saving a Test does not run it. Creating a READY Run does not start it. A successful start request does not establish a passing Test. Follow the Run to its terminal status and preserve PASSED, FAILED, ERROR, or CANCELLED exactly. Access evidence through documented authorized operations; keep temporary evidence links private.

For access or validation errors, inspect the response’s code and title, fix the cause, and retry only when appropriate. See Results and Evidence for review guidance.