> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.qa.army/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.qa.army/_mcp/server.

# API Access

> Find the public authentication and API contracts, choose authorized operations, and handle retries safely.

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](https://qa.army/auth.md): authorize a coding agent through the CLI.
* [OpenAPI document](https://api.qa.army/v1/openapi.json): request and response schemas, credential requirements, and errors.
* [Test-writing skill](https://qa.army/skill.md): author useful steps and observable expectations.

Use the [CLI guide](/interfaces/cli) for a terminal workflow that manages
authentication without exposing bearer values. Use
[Coding Agents](/interfaces/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](/results-and-evidence) for review guidance.