# CallQA developer documentation

CallQA tests voice services with **real phone calls**. You describe a test scenario, CallQA
calls your AI agent, IVR or contact center once per test case, judges each call against your
checks, and gives you a score, a verdict and the full trace. Everything in the dashboard is
also available through a REST API, so you can run voice tests from your CI/CD pipeline.

## Start here

1. [Quickstart](quickstart.md): from an API key to your first report in 5 minutes.
2. [Concepts](concepts.md): targets, scenarios, variants (test cases), environments,
   versions, runs, calls, traces, verdicts, scores and tags.

## Guides

- [Authentication and security](authentication.md): API keys, scopes, roles, rotation, IP
  restriction, audit log.
- [Writing scenarios](scenarios.md): editor, import, validate, variants, schedules, the
  assistant, the test case builder, plan limits.
- [Environments](environments.md): development, staging, production; which scenario runs
  where and when, versions and their promotion, compare environments, stability.
- [CI/CD integration](ci-cd.md): GitHub Actions, GitLab CI, Jenkins, quality gates.
- [MCP server](mcp.md): connect Claude Code, Cursor or VS Code; your coding agent runs the
  tests, reads the failures and fixes your voice agent.
- [Webhooks](webhooks.md): events, payloads, signature verification (Python, Node, Go), secret
  rotation.
- [Alerts](alerts.md): Slack and email messages when a run fails, its score drops or calls get
  slow.
- [Replay and bundles](replay.md): reproduce a call, turn it into a regression test, export a
  failure for an LLM.
- [Billing, quota and wallet](billing.md): units, prepaid wallet, spend cap, plans, credit
  errors.
- [Number verification](number-verification.md): prove you control a number, sandbox, limits.
- [Compliance review](compliance.md): what scenarios are refused, how you see it, how to
  appeal.

## Reference

- [API reference](api-reference.md): every endpoint, with the scope it needs.
  Machine readable: [`api/openapi.json`](api/openapi.json).
- [Scenario grammar reference](reference/scenario-grammar.md): every field of a scenario.
  Machine readable: [`reference/scenario.schema.json`](reference/scenario.schema.json).
- [Errors and HTTP status codes](errors.md)
- [Rate limits and other limits](rate-limits.md)
- [Versioning, compatibility and deprecation policy](versioning.md)
- [FAQ](faq.md)
- [Changelog](changelog.md)

## Examples

- [`examples/scenarios/`](../../examples/scenarios/): 7 ready-to-import scenarios (booking,
  cancellation, IVR with DTMF, payment with a test card, Spanish, transfer to a human, minimal).
- [`examples/cli/callqa`](../../examples/cli/): a one-file command line client (Python stdlib).
- [`examples/ci/`](../../examples/ci/): GitHub Action, GitHub workflows, GitLab CI, Jenkinsfile.
- [`examples/webhooks/`](../../examples/webhooks/): webhook receivers that verify signatures.

## Conventions used in these docs

- Base URL: `https://app.callqa.dev/api/v1`.
- Examples use `curl` and `jq`, with your key in the `CALLQA_API_KEY` environment variable.
- Ids are UUIDs, except API keys, tags, members and alert channels, which have integer ids.
- Timestamps are ISO 8601 in UTC. Money is in US cents (`cost_cents`, `amount_cents`).
- Durations are in milliseconds (`*_ms`) or seconds (`*_s`), as the field name says.

These pages are also served, rendered, on `https://app.callqa.dev/docs/`, with a search box
(`/docs/search/?q=...`) and the live OpenAPI document at `/docs/api/openapi.json`. The
**API explorer** at `/api/v1/docs` lets you try every endpoint with your key from the browser.

The API reference, the grammar reference, the OpenAPI document and the JSON Schema are
generated from the code, so they match the running API.