API reference

Generated by tools/gen_api_docs.py from app/api. Do not edit by hand.

Base URL: https://app.callqa.dev/api/v1. Version: 1.0.0. 124 endpoints.

• Try every endpoint in your browser: API explorer. Paste your API key once, then send real requests and copy the curl of each one.
• Machine readable: api/openapi.json (OpenAPI 3.1, import it in Postman, Insomnia or a client generator). Live schema: /api/v1/openapi.json.
• Every request needs Authorization: Bearer <API key>. See Authentication.
• Every endpoint can also answer 401, 422 (invalid input) and 429; endpoints that need a scope answer 403 when the key lacks it. See Errors.

Scope is the API key scope the endpoint needs (admin implies all). Roles are the dashboard roles allowed to do the same thing in the UI.

Index

• Organization
• Targets
• Scenarios
• Runs
• Calls
• Tags
• Versions
• Environments
• Webhooks
• Alerts
• API keys & logs
• Exports for LLMs
• Billing
• Support

Organization

GET /api/v1/audit-log

Audit log (admin).

Who did what in your organization, newest first: members, keys, webhooks, alert channels, billing, number verification, deletions. Never contains secrets. Filter by action (exact, or a prefix ending with . such as webhook.), actor_api_key_prefix and since / until.

Responses: 200 Page_AuditOut_, 401, 403, 422, 429.

GET /api/v1/exports

List exports.

Responses: 200 Page_ExportOut_, 401, 403, 422, 429.

POST /api/v1/exports

Request an export.

A full export of your organization (admin scope): a zip of JSON files with the organization and members, numbers and attestations, scenarios and test cases, runs, one file per call (trace, transcript, result), releases, tags, audit log, legal acceptances, usage and wallet ledger. Secrets are never exported. The archive is built in the background: poll GET /exports/{id} until status is done, then download download_url (signed, valid 24 hours, no API key needed). Archives are deleted after 7 days. If an export is already being built, it is returned (200).

Responses: 200 ExportOut, 201 ExportOut, 401, 403, 409 Error, 422, 429.

GET /api/v1/exports/{export_id}

Get an export.

download_url is set when status is done (a fresh 24 h link on every call).

Responses: 200 ExportOut, 401, 403, 404, 422, 429.

POST /api/v1/invitations

Invite a member.

Sends an invitation email valid 7 days. Seats are limited by the plan: when they are all taken (pending invitations count), 403 feature_not_in_plan with required_plan and upgrade_url.

Body (application/json): InvitationIn.

Responses: 201 object, 400 Error, 401, 403 Error, 422, 429.

GET /api/v1/me

Who am I.

The organization, plan and scopes of the API key used for the call.

Responses: 200 MeOut, 401, 403, 422, 429.

GET /api/v1/members

List members.

Responses: 200 list of MemberOut, 401, 403, 422, 429.

PATCH /api/v1/members/{member_id}

Change a member's role.

Body (application/json): RoleIn.

Responses: 200 MemberOut, 400 Error, 401, 403, 404, 422, 429.

DELETE /api/v1/members/{member_id}

Remove a member.

Responses: 204, 400 Error, 401, 403, 404, 422, 429.

Targets

GET /api/v1/targets

List target numbers.

Responses: 200 list of TargetOut, 401, 403, 422, 429.

POST /api/v1/targets

Register a target number.

The number is classified (country, line type). Premium-rate, shared-cost and emergency numbers are refused. A new number starts unverified: verify it (POST /targets/{id}/verification/start) before running tests on it.

Body (application/json): TargetIn.

Responses: 201 TargetOut, 400 Error, 401, 403, 422, 429.

GET /api/v1/targets/{target_id}

Get a target.

Responses: 200 TargetOut, 401, 403, 404, 422, 429.

PATCH /api/v1/targets/{target_id}

Update a target.

The phone number itself cannot change: register a new target.

Body (application/json): TargetPatch.

Responses: 200 TargetOut, 401, 403, 404, 422, 429.

DELETE /api/v1/targets/{target_id}

Delete a target (admin).

Responses: 204, 401, 403, 404, 409 Error, 422, 429.

GET /api/v1/targets/{target_id}/verification

Verification status.

Why: CallQA only calls numbers you control. Verification proves it; until then a number with a signed attestation only gets the sandbox (3 calls per 24 h, one at a time, 3 minutes max, no schedule or CI run).

Default flow (spoken_code): 1. POST /targets/{id}/verification/start (sign the attestation in the same request the first time). The response holds a 6-digit code, shown once and never stored in clear. 2. Add the phrase ("Verification code 4 8 2 1 9 3.") to the line's greeting, or to the agent prompt ("if someone asks for a verification code, answer 4 8 2 1 9 3"). 3. POST /targets/{id}/verification/call: we call the number, say "Verification, please." if the line waits for the caller to speak, and listen for 20 s.

IVR menu in front of the code: give dtmf_gate to start (for example "1w2"): after the answer we wait 1 s, press the keys (w = 0.5 s pause), then listen. The keys are remembered on the number for the next verification. renew: true verifies a verified number again without leaving verified. 4. Poll GET /targets/{id}/verification until status is verified. On failure it stays pending: last_attempt.failure_hint says what to fix, last_attempt.heard_digits what we understood, last_attempt.sip_status why a line that never answered did not (480 unavailable, 486 busy, 603 declined...); POST .../verification/retry issues a new code.

Limits: a code lives 24 h and is used by a single call; 3 failed attempts in 24 h lock the number for 24 h (a call the line does not answer counts: attempts_left, and attempts_reset_at tells when the oldest one stops counting); 10 verification calls per organization and 24 h, one at a time. A verification is valid 180 days, then the number is expired and must be verified again.

Attestation (version 2026-09-26-v2-draft), signed once per number and again when a new version becomes mandatory (attestation_outdated); the placeholders are filled in when you sign:

I, {signer_name}, confirm that I am authorized to act on behalf of {organization_name} (the "Organization") and I certify, on behalf of the Organization, that:

1. The Organization is the subscriber of the phone number {phone_number}, or holds a prior written authorization from its subscriber to have it called by automated systems using artificial or synthetic voices, for testing purposes. The Organization will keep that authorization and provide it to CallQA on request.
2. This number is not an emergency number, a premium rate or special number, or the personal line of a person who has not agreed in writing to receive these calls.
3. The calls will only be used to test the telephone system that answers this number. They will not be used for marketing, sales, surveys, or to reach any third party.
4. Where a person may answer or listen to these calls, the Organization has informed that person in advance and obtained any consent required by law for automated calls, for the use of an AI voice, and for the recording and transcription of the calls.
5. The calls, their content and any test data comply with the laws that apply to them, including laws on automated and artificial voice calls (such as the US Telephone Consumer Protection Act), telemarketing, call recording and data protection, and with the CallQA Terms of Service and Acceptable Use Policy.
6. If the Organization stops controlling this number, it will stop calling it and remove it from CallQA without delay.

I understand that CallQA relies on this attestation to place the calls, that it records my name, email, IP address and the date and time of this signature as evidence, that it may suspend calls to this number at any time, and that the Organization is responsible for any claim resulting from calls placed at its request, as set out in the Terms of Service.

Responses: 200 VerificationOut, 401, 403, 404, 422, 429.

POST /api/v1/targets/{target_id}/verification/attest

Sign the attestation.

Required once per number before verifying, and again when a new attestation version becomes mandatory. On its own it only opens the sandbox. The signed text, your name, email or API key, IP and time are kept as evidence. Text: see GET /targets/{id}/verification.

Body (application/json): AttestIn.

Responses: 200 VerificationOut, 400 Error, 401, 403 Error, 404, 409 Error, 422, 429 Error.

POST /api/v1/targets/{target_id}/verification/call

Place the verification call.

Calls the number once for the active spoken_code code (after pressing its dtmf_gate keys, if any). The call is free. Poll GET .../verification (or the call) for the result.

Body (application/json): VerificationCallIn.

Responses: 202 VerificationCallOut, 400 Error, 401, 403 Error, 404, 409 Error, 422, 429 Error.

POST /api/v1/targets/{target_id}/verification/retry

Retry with a new code.

After a failed attempt (or to replace the active code): issues a new code and cancels the previous one. Put the new phrase in the greeting or prompt before calling again.

Body (application/json): VerificationStartIn.

Responses: 201 VerificationCodeOut, 400 Error, 401, 403 Error, 404, 409 Error, 422, 429 Error.

POST /api/v1/targets/{target_id}/verification/start

Start a verification (new code).

Why: CallQA only calls numbers you control. Verification proves it; until then a number with a signed attestation only gets the sandbox (3 calls per 24 h, one at a time, 3 minutes max, no schedule or CI run).

Default flow (spoken_code): 1. POST /targets/{id}/verification/start (sign the attestation in the same request the first time). The response holds a 6-digit code, shown once and never stored in clear. 2. Add the phrase ("Verification code 4 8 2 1 9 3.") to the line's greeting, or to the agent prompt ("if someone asks for a verification code, answer 4 8 2 1 9 3"). 3. POST /targets/{id}/verification/call: we call the number, say "Verification, please." if the line waits for the caller to speak, and listen for 20 s.

IVR menu in front of the code: give dtmf_gate to start (for example "1w2"): after the answer we wait 1 s, press the keys (w = 0.5 s pause), then listen. The keys are remembered on the number for the next verification. renew: true verifies a verified number again without leaving verified. 4. Poll GET /targets/{id}/verification until status is verified. On failure it stays pending: last_attempt.failure_hint says what to fix, last_attempt.heard_digits what we understood, last_attempt.sip_status why a line that never answered did not (480 unavailable, 486 busy, 603 declined...); POST .../verification/retry issues a new code.

Limits: a code lives 24 h and is used by a single call; 3 failed attempts in 24 h lock the number for 24 h (a call the line does not answer counts: attempts_left, and attempts_reset_at tells when the oldest one stops counting); 10 verification calls per organization and 24 h, one at a time. A verification is valid 180 days, then the number is expired and must be verified again.

Attestation (version 2026-09-26-v2-draft), signed once per number and again when a new version becomes mandatory (attestation_outdated); the placeholders are filled in when you sign:

I, {signer_name}, confirm that I am authorized to act on behalf of {organization_name} (the "Organization") and I certify, on behalf of the Organization, that:

1. The Organization is the subscriber of the phone number {phone_number}, or holds a prior written authorization from its subscriber to have it called by automated systems using artificial or synthetic voices, for testing purposes. The Organization will keep that authorization and provide it to CallQA on request.
2. This number is not an emergency number, a premium rate or special number, or the personal line of a person who has not agreed in writing to receive these calls.
3. The calls will only be used to test the telephone system that answers this number. They will not be used for marketing, sales, surveys, or to reach any third party.
4. Where a person may answer or listen to these calls, the Organization has informed that person in advance and obtained any consent required by law for automated calls, for the use of an AI voice, and for the recording and transcription of the calls.
5. The calls, their content and any test data comply with the laws that apply to them, including laws on automated and artificial voice calls (such as the US Telephone Consumer Protection Act), telemarketing, call recording and data protection, and with the CallQA Terms of Service and Acceptable Use Policy.
6. If the Organization stops controlling this number, it will stop calling it and remove it from CallQA without delay.

I understand that CallQA relies on this attestation to place the calls, that it records my name, email, IP address and the date and time of this signature as evidence, that it may suspend calls to this number at any time, and that the Organization is responsible for any claim resulting from calls placed at its request, as set out in the Terms of Service.

Body (application/json): VerificationStartIn.

Responses: 201 VerificationCodeOut, 400 Error, 401, 403 Error, 404, 409 Error, 422, 429 Error.

POST /api/v1/targets/{target_id}/verify

Sign the attestation (legacy).

Kept for existing clients: same as POST .../verification/attest, returns the target. The attestation does not verify the number; see POST .../verification/start.

Body (application/json): VerifyIn.

Responses: 200 TargetOut, 400 Error, 401, 403, 404, 422, 429.

Scenarios

POST /api/v1/generation-jobs/from-call/{call_id}

Suggest a regression variant from a call.

Proposes one MANUAL variant (not saved) that reproduces what went wrong in a judged call. Add it with POST /scenarios/{id}/variants.

Generation takes 10 to 60 seconds, so it runs in the background: the answer is 202 with a job; poll GET /generation-jobs/{id} (its url) until status is done (then read result) or error.

Responses: 202 GenerationJobOut, 401, 403, 404, 409 Error, 422, 429, 503 Error.

GET /api/v1/generation-jobs/{job_id}

Get a generation job.

Responses: 200 GenerationJobOut, 401, 403, 404, 422, 429.

GET /api/v1/scenarios

List scenarios.

Responses: 200 list of ScenarioSummary, 401, 403, 422, 429.

POST /api/v1/scenarios

Create a scenario.

Body: a scenario document. The full grammar is published as JSON Schema at GET /api/v1/scenarios/schema. The landing-page shorthand (phone, persona as text, must_include, must_not, max_latency_ms at top level) is accepted. Unknown fields are rejected unless they start with x_ (kept verbatim).

A target number that does not exist yet is registered as unverified.

Body (application/json): object.

Responses: 201 ScenarioOut, 401, 403 Error, 422 ScenarioInvalid, 429.

POST /api/v1/scenarios/generate

Generate scenarios from a description.

Proposes scenario documents (not saved). Review them, then POST the ones you keep to /scenarios. Invalid proposals are filtered out.

Generation takes 10 to 60 seconds, so it runs in the background: the answer is 202 with a job; poll GET /generation-jobs/{id} (its url) until status is done (then read result) or error.

Body (application/json): GenerateIn.

Responses: 202 GenerationJobOut, 401, 403, 422, 429, 503 Error.

POST /api/v1/scenarios/import

Import a scenario from YAML.

Send the YAML as the raw body (Content-Type: application/yaml). If a non-archived scenario with the same name exists it is updated (upsert), otherwise created.

Body (application/yaml): string.

Responses: 200 ScenarioOut, 201 ScenarioOut, 401, 403 Error, 422 ScenarioInvalid, 429.

GET /api/v1/scenarios/schema

Scenario JSON Schema.

JSON Schema of the scenario grammar (generated from callqa_spec).

Responses: 200 object, 401, 403, 422, 429.

POST /api/v1/scenarios/validate

Validate a scenario without saving.

Body: a scenario document. The full grammar is published as JSON Schema at GET /api/v1/scenarios/schema. The landing-page shorthand (phone, persona as text, must_include, must_not, max_latency_ms at top level) is accepted. Unknown fields are rejected unless they start with x_ (kept verbatim).

Body (application/json): object.

Responses: 200 object, 401, 403, 422 ScenarioInvalid, 429.

GET /api/v1/scenarios/{scenario_id}

Get a scenario.

Responses: 200 ScenarioOut, 401, 403, 404, 422, 429.

PUT /api/v1/scenarios/{scenario_id}

Replace a scenario.

Body: a scenario document. The full grammar is published as JSON Schema at GET /api/v1/scenarios/schema. The landing-page shorthand (phone, persona as text, must_include, must_not, max_latency_ms at top level) is accepted. Unknown fields are rejected unless they start with x_ (kept verbatim).

Variants are matched by title: existing ones keep their id (and their history).

Body (application/json): object.

Responses: 200 ScenarioOut, 401, 403 Error, 404, 422 ScenarioInvalid, 429.

DELETE /api/v1/scenarios/{scenario_id}

Delete a scenario (admin).

Responses: 204, 401, 403, 404, 409 Error, 422, 429.

POST /api/v1/scenarios/{scenario_id}/archive

Archive a scenario.

Archived scenarios stop their schedule and are hidden from lists; their history is kept. Members may archive; only admins delete.

Responses: 200 ScenarioSummary, 401, 403, 404, 422, 429.

GET /api/v1/scenarios/{scenario_id}/export

Export as YAML or JSON.

format=yaml (default) or format=json. Round-trips with /import.

Responses: 200, 401, 403, 404, 422, 429.

GET /api/v1/scenarios/{scenario_id}/variants

List variants.

Responses: 200 list of VariantOut, 401, 403, 404, 422, 429.

POST /api/v1/scenarios/{scenario_id}/variants

Add a variant (test case).

Body (application/json): VariantIn.

Responses: 201 VariantOut, 401, 403 Error, 404, 422 ScenarioInvalid, 429.

POST /api/v1/scenarios/{scenario_id}/variants/derive

Auto-derive variants.

Adds AUTO test cases (edge cases, personas, accents, error paths) when the job completes. Requires the auto-derived coverage feature (Growth and up).

Generation takes 10 to 60 seconds, so it runs in the background: the answer is 202 with a job; poll GET /generation-jobs/{id} (its url) until status is done (then read result) or error.

Body (application/json): DeriveIn.

Responses: 202 GenerationJobOut, 401, 403 Error, 404, 422, 429, 503 Error.

POST /api/v1/scenarios/{scenario_id}/variants/from-bundle

Turn a call into a regression test.

Imports a replay bundle (or a call of yours) as a MANUAL variant: the "Add to regression suite" button.

Body (application/json): FromBundleIn.

Responses: 201 VariantOut, 400 Error, 401, 403, 404, 422 ScenarioInvalid, 429.

PATCH /api/v1/variants/{variant_id}

Update a variant.

Body (application/json): VariantPatch.

Responses: 200 VariantOut, 401, 403, 404, 422 ScenarioInvalid, 429.

DELETE /api/v1/variants/{variant_id}

Delete a variant (admin).

Responses: 204, 401, 403, 404, 422, 429.

Runs

GET /api/v1/runs

List runs.

Filter by scenario_id, status, since, environment (slug, name or id), version_id (runs attributed to the version) and tag.

Responses: 200 Page_RunOut_, 401, 403, 422, 429.

GET /api/v1/runs/{run_id}

Get a run.

Responses: 200 RunOut, 401, 403, 404, 422, 429.

DELETE /api/v1/runs/{run_id}

Delete a run and its calls.

Admin scope. Deletes the run and all its calls (trace, transcript, result, bundles) for good. Refused (409 run_not_finished) while a call of the run is queued or in progress: cancel it first. Billing lines are kept without the calls' content. Audited.

Responses: 204, 401, 403, 404, 409 Error, 422, 429.

POST /api/v1/runs/{run_id}/cancel

Cancel the calls not dialed yet.

Responses: 200 RunOut, 401, 403, 404, 422, 429.

POST /api/v1/scenarios/{scenario_id}/runs

Trigger a run (CI friendly).

Queues one call per enabled variant (or the listed ones).

CI usage: ?wait=true&threshold=80 holds the request until the run finishes (timeout seconds, default 600, capped at 900) and answers: * 200 finished and passed (score >= threshold, no failed, error or blocked call); * 412 finished and failed; * 202 still running at the timeout: poll GET /runs/{id}.

Without wait the answer is 201 with the queued run.

curl --fail alone is not a safe gate: it treats 202 as a success, so a slow run would pass. Check the status code:

code=$(curl -sS -o run.json -w '%{http_code}' -X POST --max-time 960 \
  -H "Authorization: Bearer $CALLQA_API_KEY" \
  "https://app.callqa.dev/api/v1/scenarios/$SCENARIO/runs?wait=true&timeout=900&threshold=80")
[ "$code" = "200" ] || exit 1

The wait is asynchronous on the server (no worker is held), but proxies in front of your runner may cut a request open for minutes: the CLI polls instead.

Body (application/json): TriggerIn.

Responses: 200 RunOut, 201 RunOut, 202 RunOut, 400 Error, 401, 403 Error, 404, 412 RunOut, 422, 429.

Calls

GET /api/v1/calls

List calls.

Filter by status (e.g. error, blocked_insufficient_credit), verdict, run_id, since, environment.

Responses: 200 Page_CallOut_, 401, 403, 422, 429.

GET /api/v1/calls/{call_id}

Get a call.

Includes the ResolvedRun, the result (verdicts with evidence, metrics, score) and the transcript.

Responses: 200 CallDetailOut, 401, 403, 404, 422, 429.

DELETE /api/v1/calls/{call_id}

Delete a call.

Admin scope. Deletes the call, its trace, transcript, result and bundles for good. Refused with 409 while the call is not finished (call_not_finished) and for number verification calls, kept as evidence (verification_record). Billing lines are kept without the call's content. Audited.

Responses: 204, 401, 403, 404, 409 Error, 422, 429.

GET /api/v1/calls/{call_id}/bundle

Export a replay bundle.

A self-contained JSON file (callqa_spec.ReplayBundle): resolved run, runtime (models, voices, settings), full trace and result. Replay it with POST /replays or import it as a regression test with POST /scenarios/{id}/variants/from-bundle.

Responses: 200 object, 401, 403, 404, 422, 429.

GET /api/v1/calls/{call_id}/events

Call trace.

The append-only event trace (callqa_spec.CallEvent), by seq.

Responses: 200 Page_EventOut_, 401, 403, 404, 422, 429.

GET /api/v1/calls/{call_id}/recording

Download the call audio.

The stereo WAV of the call (16 bit PCM, 16 kHz): left track our test caller, right track your line. Sample 0 is the dialing event: a trace instant t_ms is at (t_ms - recording.start_ms) / 1000 seconds. Supports HTTP Range. 404 when the organization does not record audio, or once the recording expired (audio retention).

Responses: 200, 206, 401, 403, 404, 422, 429.

POST /api/v1/replays

Replay a call.

Creates a new call with exactly the same ResolvedRun (and by default the same runtime). The bundle's target must be a number of your organization; normal checks apply (verification, credit, concurrency).

Body (application/json): ReplayIn.

Responses: 201 CallOut, 400 Error, 401, 403, 404 Error, 422, 429.

Tags

GET /api/v1/tags

List or search tags.

Tags are free keywords (a code name, a customer, a team) on scenarios, runs, versions and numbers; CallQA gives them no meaning of its own. With q, the autocomplete: names starting with q first, then containing it, most used first, at most limit (default 10, max 50).

Responses: 200 list of TagSuggestion, 401, 403, 422, 429.

POST /api/v1/tags

Create a tag.

Body (application/json): TagIn.

Responses: 201 TagOut, 401, 403, 409 Error, 422, 429.

POST /api/v1/tags/bulk

Tag or untag many objects.

Adds add and removes remove on every listed scenario, run, version and number (by id). Tags to add are created when new. An id of another organization answers 404 unknown_object and nothing is changed.

Body (application/json): TagBulkIn.

Responses: 200 TagBulkOut, 400 Error, 401, 403, 404 Error, 422, 429.

GET /api/v1/tags/{tag_id}

Get a tag.

Responses: 200 TagOut, 401, 403, 404, 422, 429.

PATCH /api/v1/tags/{tag_id}

Update a tag.

Renaming a tag keeps it on its scenarios and runs.

Body (application/json): TagPatch.

Responses: 200 TagOut, 401, 403, 404, 409 Error, 422, 429.

DELETE /api/v1/tags/{tag_id}

Delete a tag (admin).

Responses: 204, 401, 403, 404, 422, 429.

Versions

GET /api/v1/releases

List releases (deprecated).

Deprecated since 2026-09-27, removed on 2027-03-31.

Use GET /versions.

Responses: 200 list of ReleaseOut, 401, 403, 422, 429.

POST /api/v1/releases

Tag a release (deprecated).

Deprecated since 2026-09-27, removed on 2027-03-31.

Use POST /versions.

Body (application/json): ReleaseIn.

Responses: 201 ReleaseOut, 400 Error, 401, 403, 409 Error, 422, 429.

GET /api/v1/releases/{release_id}

Get a release (deprecated).

Deprecated since 2026-09-27, removed on 2027-03-31.

Use GET /versions/{id}.

Responses: 200 ReleaseOut, 401, 403, 404, 422, 429.

PATCH /api/v1/releases/{release_id}

Update a release (deprecated).

Deprecated since 2026-09-27, removed on 2027-03-31.

Use PATCH /versions/{id}.

Body (application/json): ReleasePatch.

Responses: 200 ReleaseOut, 400 Error, 401, 403, 404, 409 Error, 422, 429.

DELETE /api/v1/releases/{release_id}

Delete a release (deprecated, admin).

Deprecated since 2026-09-27, removed on 2027-03-31.

Use DELETE /versions/{id}.

Responses: 204, 401, 403, 404, 422, 429.

POST /api/v1/releases/{release_id}/promote

Promote a release (deprecated).

Deprecated since 2026-09-27, removed on 2027-03-31.

Use POST /versions/{id}/promote.

Body (application/json): PromoteIn.

Responses: 201 ReleaseOut, 400 Error, 401, 403, 404, 409 Error, 422, 429.

GET /api/v1/versions

List versions.

Newest first. environment (slug, name or id) keeps one environment, tag the versions carrying a tag, q a part of the label, git ref or sha.

Responses: 200 Page_VersionOut_, 401, 403, 422, 429.

POST /api/v1/versions

Create a version.

A version of your code in one environment, from deployed_at (default now). Runs of that environment are attributed to it until the next version. 409 already_exists when the label exists in the environment. CI can instead send version when it triggers a run.

Body (application/json): VersionIn.

Responses: 201 VersionOut, 400 Error, 401, 403, 409 Error, 422, 429.

GET /api/v1/versions/{version_id}

Get a version.

Responses: 200 VersionOut, 401, 403, 404, 422, 429.

PATCH /api/v1/versions/{version_id}

Update a version.

Body (application/json): VersionPatch.

Responses: 200 VersionOut, 400 Error, 401, 403, 404, 409 Error, 422, 429.

DELETE /api/v1/versions/{version_id}

Delete a version (admin).

Its runs are kept; they fall back to the previous version of the environment.

Responses: 204, 401, 403, 404, 422, 429.

POST /api/v1/versions/{version_id}/promote

Promote a version to another environment.

The same code in the next environment (staging to production), from deployed_at (default now): label, git fields, notes, number and tags travel with it. 409 already_exists when the label is already there.

Body (application/json): VersionPromoteIn.

Responses: 201 VersionOut, 400 Error, 401, 403, 404, 409 Error, 422, 429.

Environments

GET /api/v1/environments

List environments.

In promotion order. Every organization has one default environment (is_default), used by runs and versions that name none.

Responses: 200 list of EnvironmentOut, 401, 403, 422, 429.

POST /api/v1/environments

Create an environment.

Body (application/json): EnvironmentIn.

Responses: 201 EnvironmentOut, 400 Error, 401, 403, 409 Error, 422, 429.

GET /api/v1/environments/compare

Compare environments (Growth and up).

Side a vs side b (for example a=staging&b=production): overall KPIs, per scenario, and the test cases whose last verdict differs. Narrow a side to one version with a_version / b_version (version id), and to one scenario with scenario_id. Without a version, a side covers the last days days. a_release / b_release are the deprecated names of a_version / b_version.

Responses: 200 CompareOut, 400 Error, 401, 403 Error, 422, 429.

GET /api/v1/environments/stability

Stability per environment (Growth and up).

Over the last days (7, 30 or 90): tests, pass rate, average score, p95 latency, flaky test cases and last run of each environment.

Responses: 200 list of StabilityOut, 401, 403 Error, 422, 429.

GET /api/v1/environments/{env_id}

Get an environment.

By id or slug.

Responses: 200 EnvironmentOut, 401, 403, 404, 422, 429.

PATCH /api/v1/environments/{env_id}

Update an environment.

Body (application/json): EnvironmentPatch.

Responses: 200 EnvironmentOut, 400 Error, 401, 403, 404, 409 Error, 422, 429.

DELETE /api/v1/environments/{env_id}

Delete an environment (admin).

Refused (409 environment_in_use) while runs or versions belong to it, and for the default environment (409 default_required).

Responses: 204, 401, 403, 404, 409 Error, 422, 429.

PUT /api/v1/environments/{env_id}/numbers

Set the number dialed in an environment.

Runs of this environment dial number_id instead of target_id. Both are numbers of your organization, each verified on its own.

Body (application/json): NumberIn.

Responses: 200 EnvironmentOut, 400 Error, 401, 403, 404, 422, 429.

GET /api/v1/environments/{env_id}/scenarios

Scenarios of an environment.

The scenarios activated in (or bound to) this environment.

Responses: 200 list of BindingOut, 401, 403, 404, 422, 429.

POST /api/v1/environments/{env_id}/scenarios

Bind, pause or unbind many scenarios.

One call for a multi-select or a drag and drop: enable, disable or remove the listed scenarios in this environment, optionally with the same schedule, timezone, call_window for all. An id of another organization answers 404 and nothing changes.

Body (application/json): BulkBindingIn.

Responses: 200 BulkBindingOut, 400 Error, 401, 403, 404, 422, 429.

GET /api/v1/matrix

What runs where, and what passes.

For every scenario x environment: activated or not, schedule, last completed run (verdict, score, version), trend of the last trend_runs runs; for the last versions versions of each environment: the scenarios that pass, warn, fail or were not tested. Filters: environment and tag (repeat them), scenario_id (repeat), q (part of a scenario name), bound_only.

Responses: 200 MatrixOut, 401, 403, 422, 429.

GET /api/v1/scenarios/{scenario_id}/environments

Environments of a scenario.

Where the scenario runs, with the schedule, the call window and the number dialed in each environment.

Responses: 200 list of BindingOut, 401, 403, 404, 422, 429.

PUT /api/v1/scenarios/{scenario_id}/environments/{env_id}

Activate or schedule a scenario in an environment.

Creates the binding when needed. Fields left out keep their value. Each environment has its own schedule and window.

Body (application/json): BindingIn.

Responses: 200 BindingOut, 400 Error, 401, 403, 404, 422, 429.

DELETE /api/v1/scenarios/{scenario_id}/environments/{env_id}

Remove a scenario from an environment.

Deletes the binding and its schedule. Past runs are kept.

Responses: 204, 401, 403, 404, 422, 429.

Webhooks

GET /api/v1/webhooks

List webhook endpoints.

Payloads are JSON {id, type, created, data} signed with HMAC-SHA256:

CallQA-Signature: t=<unix ts>,v1=<hex hmac_sha256(secret, "<ts>.<raw body>")>

During a secret rotation the header carries one v1 per valid secret: accept the delivery if any v1 matches. Verify in constant time and reject timestamps older than 5 minutes. Failed deliveries are retried after 1 min, 5 min, 30 min, 2 h and 6 h.

Events: call.completed, call.failed, call.blocked, call.regressed, call.recovered, suite_run.started, suite_run.completed, suite_run.failed, score.dropped, version.created, version.promoted, release.created, release.promoted, wallet.low_balance

Responses: 200 list of WebhookOut, 401, 403, 422, 429.

POST /api/v1/webhooks

Create a webhook endpoint.

Payloads are JSON {id, type, created, data} signed with HMAC-SHA256:

CallQA-Signature: t=<unix ts>,v1=<hex hmac_sha256(secret, "<ts>.<raw body>")>

During a secret rotation the header carries one v1 per valid secret: accept the delivery if any v1 matches. Verify in constant time and reject timestamps older than 5 minutes. Failed deliveries are retried after 1 min, 5 min, 30 min, 2 h and 6 h.

Events: call.completed, call.failed, call.blocked, call.regressed, call.recovered, suite_run.started, suite_run.completed, suite_run.failed, score.dropped, version.created, version.promoted, release.created, release.promoted, wallet.low_balance

Body (application/json): WebhookIn.

Responses: 201 WebhookCreated, 400 Error, 401, 403, 422, 429.

GET /api/v1/webhooks/{webhook_id}

Get a webhook endpoint.

Responses: 200 WebhookOut, 401, 403, 404, 422, 429.

PATCH /api/v1/webhooks/{webhook_id}

Update a webhook endpoint.

Change the URL, the events, the description, or pause it (enabled: false). The signing secret does not change: use rotate-secret.

Body (application/json): WebhookPatch.

Responses: 200 WebhookOut, 400 Error, 401, 403, 404, 422, 429.

DELETE /api/v1/webhooks/{webhook_id}

Delete a webhook endpoint.

Responses: 204, 401, 403, 404, 422, 429.

GET /api/v1/webhooks/{webhook_id}/deliveries

Delivery log of an endpoint.

Responses: 200 Page_DeliveryOut_, 401, 403, 404, 422, 429.

POST /api/v1/webhooks/{webhook_id}/rotate-secret

Rotate the signing secret.

Returns the new secret (shown once). During grace_period_hours (default 24, at most 168) every delivery is signed with both secrets (two v1 in CallQA-Signature), so you can deploy the new one without losing events.

Body (application/json): SecretRotateIn.

Responses: 200 WebhookCreated, 400 Error, 401, 403, 404, 422, 429.

POST /api/v1/webhooks/{webhook_id}/test

Send a test event now.

Responses: 200 DeliveryOut, 401, 403, 404, 422, 429.

Alerts

GET /api/v1/alert-channels

List alert channels.

Alert channels warn people in Slack (incoming webhook) or by email when a run run completes and one of the channel's rules matches: the run failed (on_failure), its score is under on_score_below, or a call's p95 latency is above on_latency_p95_above_ms. One message per channel and run at most, sent within seconds by the dispatcher and retried after 1, 5 and 30 minutes.

The Slack webhook URL is a secret: it must be an https://hooks.slack.com/ URL, and it is never returned in full. For machine integrations, use webhooks.

Responses: 200 list of AlertChannelOut, 401, 403, 422, 429.

POST /api/v1/alert-channels

Create an alert channel.

Alert channels warn people in Slack (incoming webhook) or by email when a run run completes and one of the channel's rules matches: the run failed (on_failure), its score is under on_score_below, or a call's p95 latency is above on_latency_p95_above_ms. One message per channel and run at most, sent within seconds by the dispatcher and retried after 1, 5 and 30 minutes.

The Slack webhook URL is a secret: it must be an https://hooks.slack.com/ URL, and it is never returned in full. For machine integrations, use webhooks.

Body (application/json): AlertChannelIn.

Responses: 201 AlertChannelOut, 400 Error, 401, 403, 422, 429.

GET /api/v1/alert-channels/{channel_id}

Get an alert channel.

Responses: 200 AlertChannelOut, 401, 403, 404, 422, 429.

PATCH /api/v1/alert-channels/{channel_id}

Update an alert channel.

Only the fields you send change. null on a threshold removes that rule. The kind cannot change.

Body (application/json): AlertChannelPatch.

Responses: 200 AlertChannelOut, 400 Error, 401, 403, 404, 422, 429.

DELETE /api/v1/alert-channels/{channel_id}

Delete an alert channel.

Responses: 204, 401, 403, 404, 422, 429.

POST /api/v1/alert-channels/{channel_id}/test

Send a test alert.

Sends a test message now and tells whether it went through. Limited to 5 per minute per channel.

Responses: 200 AlertTestOut, 401, 403, 404, 422, 429.

API keys & logs

GET /api/v1/api-keys

List API keys.

Responses: 200 list of ApiKeyOut, 401, 403, 422, 429.

POST /api/v1/api-keys

Create an API key.

The full key is returned once; only a hash is stored. allowed_cidrs restricts where it can be used from.

Body (application/json): ApiKeyIn.

Responses: 201 ApiKeyCreated, 400 Error, 401, 403, 422, 429.

GET /api/v1/api-keys/{key_id}

Get an API key.

Responses: 200 ApiKeyOut, 401, 403, 404, 422, 429.

PATCH /api/v1/api-keys/{key_id}

Rename or restrict an API key.

Scopes cannot change: create a new key instead.

Body (application/json): ApiKeyPatch.

Responses: 200 ApiKeyOut, 400 Error, 401, 403, 404, 422, 429.

DELETE /api/v1/api-keys/{key_id}

Revoke an API key.

Responses: 204, 401, 403, 404, 422, 429.

POST /api/v1/api-keys/{key_id}/rotate

Rotate an API key.

Creates a replacement with the same name, scopes, networks and expiry, returned once. The old key keeps working for grace_period_hours (default 24, at most 168, 0 revokes it now), then expires: deploy the new one in between.

Body (application/json): KeyRotateIn.

Responses: 201 ApiKeyCreated, 400 Error, 401, 403, 404, 422, 429.

GET /api/v1/api-logs

API request journal.

Every authenticated API request of your organization (method, path, status, duration, key, IP). Bodies are never stored.

Responses: 200 Page_ApiLogOut_, 401, 403, 422, 429.

Exports for LLMs

GET /api/v1/calls/{call_id}/llm-export

Export a call for an LLM.

A report made to be pasted into an LLM (a chat assistant or a coding agent) that will fix your voice agent: the scenario, the results, every failed check with the judge's quote, a readable transcript (AGENT = your agent, CALLER = our test caller), metrics, the judge's recommendations and a primer asking for a fix.

format=markdown (default) answers text/markdown; format=json answers the same document as compact JSON (format: "callqa.llm_report", version, level).

Responses: 200 object, 401, 403, 404, 422, 429.

GET /api/v1/runs/{run_id}/llm-export

Export a run for an LLM.

A report made to be pasted into an LLM (a chat assistant or a coding agent) that will fix your voice agent: the scenario, the results, every failed check with the judge's quote, a readable transcript (AGENT = your agent, CALLER = our test caller), metrics, the judge's recommendations and a primer asking for a fix.

format=markdown (default) answers text/markdown; format=json answers the same document as compact JSON (format: "callqa.llm_report", version, level). The failed calls (up to 5) are detailed.

Responses: 200 object, 401, 403, 404, 422, 429.

GET /api/v1/scenarios/{scenario_id}/llm-export

Export a scenario for an LLM.

A report made to be pasted into an LLM (a chat assistant or a coding agent) that will fix your voice agent: the scenario, the results, every failed check with the judge's quote, a readable transcript (AGENT = your agent, CALLER = our test caller), metrics, the judge's recommendations and a primer asking for a fix.

format=markdown (default) answers text/markdown; format=json answers the same document as compact JSON (format: "callqa.llm_report", version, level). Covers the scenario YAML, its last 5 runs, the checks that fail most and the last 3 failed calls.

Responses: 200 object, 401, 403, 404, 422, 429.

Billing

GET /api/v1/billing/forecast

Forecast of the month.

What the enabled schedules will consume until the quota resets (1st of next month, UTC), per schedule and environment: runs left x test cases x destination weight x average 10 minute slices observed over 30 days (maximum duration when a scenario never ran). Compared with the quota, bonus calls, overage settings and cap. Manual, API and CI runs are not forecast.

Responses: 200 ForecastOut, 401, 403, 422, 429.

POST /api/v1/billing/portal

Open the billing portal.

Returns a Stripe billing portal URL: change or cancel the plan, update the payment method, download invoices.

Body (application/json): PortalIn.

Responses: 200 CheckoutOut, 400 Error, 401, 403, 422, 429, 503 Error.

GET /api/v1/billing/referral

Your referral link.

Both organizations get the bonus calls when the referred one starts its first paid subscription. Referring yourself (a member of your organization, the same Stripe customer) or an existing customer gives nothing.

Responses: 200 ReferralOut, 401, 403, 422, 429.

GET /api/v1/billing/settings

Overage, spend cap and alerts.

Paid overage on/off, its monthly cap (wallet spend), what happens at the limit, and the wallet.low_balance threshold.

Responses: 200 BillingSettingsOut, 401, 403, 422, 429.

PATCH /api/v1/billing/settings

Change overage, the spend cap or the low balance threshold (admin).

Only the fields you send change; null removes the cap or turns wallet.low_balance off. When the cap is reached, new calls are not placed (blocked_insufficient_credit, block reason spend_cap_reached) until the next month or a higher cap. allow_paid_overage: false stops calls once the quota and bonus calls are used (overage_disabled); on_limit: pause_schedules also pauses the schedules until the 1st of next month.

Body (application/json): BillingSettingsPatch.

Responses: 200 BillingSettingsOut, 401, 403, 422, 429.

GET /api/v1/billing/subscription

Current subscription.

Responses: 200 SubscriptionOut, 401, 403, 422, 429.

POST /api/v1/billing/subscription/checkout

Subscribe to a plan.

Returns a Stripe Checkout URL for a first subscription. If your organization already has an active Stripe subscription the answer is 409 (subscription_exists): change plan, interval or payment method in the billing portal (POST /billing/portal).

Body (application/json): SubscriptionCheckoutIn.

Responses: 200 CheckoutOut, 400 Error, 401, 403, 409 Error, 422, 429, 503 Error.

GET /api/v1/plans

Public plans.

Plans you can subscribe to with POST /billing/subscription/checkout.

Responses: 200 list of PlanPublicOut, 401, 403, 422, 429.

GET /api/v1/usage

Quota usage this month.

Quota periods are calendar months (UTC). held = units reserved by calls in progress.

Responses: 200 UsageOut, 401, 403, 422, 429.

GET /api/v1/wallet

Wallet balance.

Calls beyond the monthly quota are paid from a prepaid wallet, at your plan's overage price times the destination weight. Credit is reserved before a call is dialed and the unused part is released after. When the wallet cannot cover a call, the call is not placed and ends with status blocked_insufficient_credit: top up with POST /wallet/checkout. Top-ups are between $20 and $5,000 (amount_cents 2000 to 500000).

Responses: 200 WalletOut, 401, 403, 422, 429.

POST /api/v1/wallet/checkout

Top up the wallet.

Calls beyond the monthly quota are paid from a prepaid wallet, at your plan's overage price times the destination weight. Credit is reserved before a call is dialed and the unused part is released after. When the wallet cannot cover a call, the call is not placed and ends with status blocked_insufficient_credit: top up with POST /wallet/checkout. Top-ups are between $20 and $5,000 (amount_cents 2000 to 500000).

Returns a Stripe Checkout URL. The wallet is credited when Stripe confirms the payment (webhook), not before.

Body (application/json): CheckoutIn.

Responses: 200 CheckoutOut, 400 Error, 401, 403, 422, 429, 503 Error.

GET /api/v1/wallet/transactions

Wallet ledger.

Append-only ledger: every balance change has a line.

Responses: 200 Page_WalletTxOut_, 401, 403, 422, 429.

Support

GET /api/v1/support/tickets

List support tickets.

Ask the CallQA team: a bug, a question, feedback, a billing matter or an abuse report. A person of the team answers, usually within a few hours on business days; the answer is emailed to the author (and to the organization's admins when an API key opened the ticket) and readable here. Statuses: open (the team has to answer), waiting_customer (the team waits for you), answered, closed. A reply reopens a ticket.

Never paste a secret (API key, password, token): anything that looks like one is replaced by [redacted secret] before it is stored.

Responses: 200 Page_TicketOut_, 401, 403, 422, 429.

POST /api/v1/support/tickets

Open a support ticket.

Ask the CallQA team: a bug, a question, feedback, a billing matter or an abuse report. A person of the team answers, usually within a few hours on business days; the answer is emailed to the author (and to the organization's admins when an API key opened the ticket) and readable here. Statuses: open (the team has to answer), waiting_customer (the team waits for you), answered, closed. A reply reopens a ticket.

Never paste a secret (API key, password, token): anything that looks like one is replaced by [redacted secret] before it is stored.

At most 20 new tickets a day per organization (429 rate_limited beyond).

Body (application/json): TicketIn.

Responses: 201 TicketDetail, 400 Error, 401, 403, 422 Error, 429.

GET /api/v1/support/tickets/{ticket_id}

Get a support ticket.

The ticket and every message, oldest first: the answers of the CallQA team have author staff.

Responses: 200 TicketDetail, 401, 403, 404, 422, 429.

POST /api/v1/support/tickets/{ticket_id}/close

Close a support ticket.

When the matter is solved. A later reply reopens it.

Responses: 200 TicketDetail, 401, 403, 404, 422, 429.

POST /api/v1/support/tickets/{ticket_id}/messages

Reply to a support ticket.

Adds a message and reopens the ticket (status open): the team is alerted. Never paste a secret.

Body (application/json): MessageIn.

Responses: 201 TicketDetail, 400 Error, 401, 403, 404, 422, 429.

Schemas

Request and response objects, as named above. Full definitions in api/openapi.json under components.schemas.

ActiveCode

AlertChannelIn

AlertChannelOut

AlertChannelPatch

AlertTestOut

ApiKeyCreated

ApiKeyIn

ApiKeyOut

ApiKeyPatch

ApiLogOut

AttestIn

AuditOut

BillingSettingsOut

BillingSettingsPatch

BindingIn

BindingOut

BulkBindingIn

BulkBindingOut

CallDetailOut

CallOut

CheckoutIn

CheckoutOut

CiOut

CompareOut

ComplianceOut

ComplianceReasonOut

DeliveryOut

DeriveIn

EnvironmentForecastOut

EnvironmentIn

EnvironmentNumberOut

EnvironmentOut

EnvironmentPatch

Error

EventOut

ExportOut

ForecastOut

FromBundleIn

GenerateIn

GenerationJobOut

InvitationIn

KeyRotateIn

KpisOut

LastAttempt

MatrixCell

MatrixEntry

MatrixEnvironment

MatrixOut

MatrixRun

MatrixScenario

MatrixTotals

MatrixTrend

MatrixVersion

MatrixVersionRow