ConvergeQA Developer and Agent API Beta

The ConvergeQA API gives you programmatic access to the same multi-model review engine that powers the web interface. Run Compare reviews, manage templates, and download review records from your own code, IDE, or agent pipeline.

This Developer and Agent area is Beta. API key generation is available on Pro and Enterprise accounts. Active accounts can generate up to 5 keys. API calls use the same credit balance as web reviews.

Agent workflows

Most human-in-the-loop agent use starts with a Developer API key generated on this page. Service-account workflows are separate organization-owned credentials created by org admins on the Organization page for bounded delegated environments such as Codex, Claude-style tools, compatible IDEs, MCP clients, and GitHub Actions.

The local AI coworker skill templates and CLI clients live on the AI Coworkers page. Use that advanced workflow tier for automation and headless service-account use after the MCP tools are connected.

Get started with MCP in 3 steps

  1. Generate an API key in the API Keys section below
  2. Add the ConvergeQA MCP server to your agent. The pattern is the same in every MCP-capable client (Claude Code, Codex, OpenCode, Cursor, OpenClaw, Hermes, and others): command uvx, args convergeqa-mcp reviews or convergeqa-mcp compare, API key in the environment. For example, in Claude Code: 
    claude mcp add convergeqa-reviews --env CONVERGEQA_API_KEY=$CONVERGEQA_API_KEY -- uvx convergeqa-mcp reviews
claude mcp add convergeqa-compare --env CONVERGEQA_API_KEY=$CONVERGEQA_API_KEY -- uvx convergeqa-mcp compare
    JSON and TOML config examples for other clients

    JSON-config clients such as Claude Desktop, OpenCode, and Cursor (shown for claude_desktop_config.json; add under mcpServers):

    "convergeqa-reviews": { "command": "uvx", "args": ["convergeqa-mcp", "reviews"], "env": { "CONVERGEQA_API_KEY": "${CONVERGEQA_API_KEY}" } }

    TOML-config clients such as Codex CLI (~/.codex/config.toml):

    [mcp_servers.convergeqa-reviews]
command = "uvx"
args = ["convergeqa-mcp", "reviews"]
env = { "CONVERGEQA_API_KEY" = "<your key>" }

    If your client does not expand environment placeholders, set the key in the client's own environment instead of the config file.

  3. Run your first agent review with Compare, Critique, or Iterate directly from the agent. Reviews consume paid credits, and the responsible individual decides what to accept. Optionally verify the API connection first: 
    curl -H "X-API-Key: YOUR_KEY" https://convergeqa.net/api/v1/health

The open-source package is available on GitHub and PyPI. The reviews and compare servers are listed in the official MCP Registry.

For advanced automation, use the supported skill and CLI examples below rather than the retired synchronous review endpoints.

API Keys

The keys generated here are personal Developer API keys. Store them as CONVERGEQA_API_KEY and send them as X-API-Key. A local variable name such as ConvergeQA_Service_Account_Key does not make the key a service-account credential. Org service-account keys are created by org admins on the Organization page, are sent as X-Service-Account-Key, and start with cqa_sa_.

Loading...

Authentication

Agent Review Workflows

Compare, Critique, and Iterate

Use the Compare due-diligence path for agent packet and bundle workflows, /api/v1/critique for an audit packet without changing the source document, and /api/v1/iterate for revision loops with accept/decline decisions. The older synchronous /api/v1/quick and /api/v1/compare endpoints are retired.

Developer API keys use the X-API-Key header and are the normal path for human-directed AI coworker calls. Org admins can create org-owned service-account credentials on the Organization page; the default Organization-page key is a full agent workflow key for approved Compare due-diligence, Critique, and Iterate clients, including packet reads, bundle exports, and delegated Critique/Iterate finish decisions.

Local CLI and MCP agent wrappers are available for Compare due diligence, Critique, and Iterate. They read credentials from environment variables, avoid literal key arguments, and return concise machine-facing packet metadata.

Agent setup checklist

  1. Choose the review mode first. Use Compare for independent model answers to the same query, Critique for an audit report where the source should not be edited, and Iterate when the agent or user will accept/decline proposed revisions.
  2. Store credentials in environment variables. Developer API keys should be read from CONVERGEQA_API_KEY and sent as X-API-Key. Org service-account keys should be read from CONVERGEQA_SERVICE_ACCOUNT_KEY and sent as X-Service-Account-Key. Do not pass literal keys in command arguments, screenshots, logs, or saved artifacts.
  3. Use approved input only. Agent clients work best from a UTF-8 prompt file plus optional reference-material file. Do not submit protected health information (PHI), secrets, private credentials, or regulated identifiers.
  4. Declare tier and panel. Always include selected models. For Critique and Iterate starts, include model_tier (budget, premium, or frontier) and a synthesis_model when synthesis is used. For Compare due diligence, model_tier is only for org service-account credentials; Developer API-key callers should omit it.
  5. Make decision control explicit. Human-guided runs should pause at the packet/session checkpoint. Agent-driven Critique or Iterate should state the decision policy, round limit, and stop condition before the first live call.
  6. Export before cleanup. Poll status, retrieve the packet/session, submit decisions, and export the bundle before revoking a temporary service-account credential. Use idempotency keys for retryable starts.

Compare note: use the supported Compare due-diligence client, which targets /api/v1/due-diligence/compare when that private path is enabled for your credential. The retired synchronous Compare path returns a retirement response and does not dispatch model work.

Endpoint Reference

Agent due-diligence Compare uses the supported CLI/MCP client and private /api/v1/due-diligence/compare path when enabled for the credential. Use that path for packet JSON, owner-authenticated bundles, idempotency, and due-diligence record claims. Retired synchronous review endpoints remain listed only so older callers can recognize the replacement path.

▶ GET /api/v1/health Check API status

Returns API status. Use this to verify your key works.

curl -H "X-API-Key: YOUR_KEY" https://convergeqa.net/api/v1/health
▶ GET /api/v1/models List available AI models

Returns available AI models and their metadata.

curl -H "X-API-Key: YOUR_KEY" https://convergeqa.net/api/v1/models
▶ GET /api/v1/templates List review templates

Returns your saved review templates (built-in + custom).

curl -H "X-API-Key: YOUR_KEY" https://convergeqa.net/api/v1/templates
▶ POST /api/v1/templates Create a review template

Save a custom review template for reuse.

curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"name": "My Template", "system_prompt": "You are a medical reviewer...", "prompt_task": "Review for clinical accuracy"}' \
  https://convergeqa.net/api/v1/templates
▶ POST /api/v1/quick Retired legacy quick review

Retired legacy endpoint. Use the supported Compare due-diligence, Critique, or Iterate clients for charged review workflows.

curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "Review this paragraph for accuracy", "model": "claude-opus-5"}' \
  https://convergeqa.net/api/v1/quick
▶ POST /api/v1/compare Retired legacy Compare

Retired legacy endpoint. Use the supported Compare due-diligence client for charged multi-model Compare workflows with packets and bundles.

curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "Is aspirin recommended for primary prevention of cardiovascular disease?", "models": ["claude-opus-5", "gpt-5.6-sol", "gemini-3.1-pro"]}' \
  https://convergeqa.net/api/v1/compare
▶ POST /api/v1/critique/start Start a Critique audit session

Start an agent-friendly Critique session. Critique produces a structured audit packet and leaves the submitted source unchanged.

Parameters:

  • prompt (string, required) - content to audit
  • models (array, required) - model IDs to dispatch to
  • synthesis_model (string) - model for audit synthesis
  • template (string) - review policy/template name, default General. Its system prompt and specialist roles are applied to the panel unless you send your own system_prompt or specialist_roles. An unrecognized name is rejected rather than run as a generic review.
  • system_prompt (string, optional) - overrides the template's system prompt
  • specialist_roles (array, optional) - [{"model_id": "...", "role": "..."}, ...]; overrides the template's roles
  • model_tier - required for service-account credentials
curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "Audit this synthetic deliverable for accuracy.", "models": ["claude-opus-5", "gpt-5.6-sol"], "synthesis_model": "claude-opus-5", "template": "General", "model_tier": "budget"}' \
  https://convergeqa.net/api/v1/critique/start

Returns: {"ok": true, "job_id": "...", "session_id": "..."}

▶ GET /api/v1/critique/status/{job_id} Poll Critique job progress

Poll the initial Critique dispatch job. When complete, fetch the session packet for agent-facing findings and decision metadata.

curl -H "X-API-Key: YOUR_KEY" https://convergeqa.net/api/v1/critique/status/YOUR_JOB_ID

Status values: queued, processing, complete, failed

▶ GET /api/v1/critique/{session_id}/packet Fetch Critique agent packet

Retrieve the machine-facing Critique packet with findings, decisions, audit status, safe attribution, and credit/billing status when available.

curl -H "X-API-Key: YOUR_KEY" https://convergeqa.net/api/v1/critique/YOUR_SESSION_ID/packet
▶ POST /api/v1/critique/{session_id}/decide Submit Critique decisions

Submit decisions on Critique findings, then continue, finish, or pause the session. Supported decision actions are agree, disagree, and go_deeper.

curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"action": "finish", "decisions": [{"rec_index": 0, "action": "agree"}]}' \
  https://convergeqa.net/api/v1/critique/YOUR_SESSION_ID/decide
▶ POST /api/v1/critique/{session_id}/export Download Critique audit bundle

Export a Critique session as an audit bundle after review decisions are complete.

curl -H "X-API-Key: YOUR_KEY" -o critique.zip \
  -X POST https://convergeqa.net/api/v1/critique/YOUR_SESSION_ID/export
▶ GET /api/v1/critique/sessions List Critique sessions

List Critique sessions for the authenticated account or scoped service-account credential.

curl -H "X-API-Key: YOUR_KEY" https://convergeqa.net/api/v1/critique/sessions
▶ POST /api/v1/iterate/start Start an Iterate revision session

Start a full iterative refinement session. The system runs Compare + Synthesis, then returns structured recommendations for you to accept or decline.

Parameters:

  • prompt (string, required) - document or content to review
  • models (array, required) - model IDs to dispatch to
  • synthesis_model (string) - model for synthesis (default: claude-opus-5)
  • system_prompt (string) - custom system prompt
  • specialist_roles (array) - [{"model_id": "...", "role": "..."}, ...]
  • reference_material (string) - context that informs but isn't edited
  • compress (boolean) - optional context compression for unusually large reviews (default: false)
  • model_tier - required for service-account credentials
curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "Review this document for accuracy...", "models": ["claude-opus-5", "gpt-5.6-sol", "gemini-3.1-pro"], "synthesis_model": "claude-opus-5", "model_tier": "budget"}' \
  https://convergeqa.net/api/v1/iterate/start

Returns: {"ok": true, "job_id": "...", "session_id": "..."}

▶ GET /api/v1/iterate/status/{job_id} Poll iterate job progress

Poll the status of an iterate job. When complete, the result contains the synthesized document and structured recommendations.

curl -H "X-API-Key: YOUR_KEY" https://convergeqa.net/api/v1/iterate/status/YOUR_JOB_ID

Status values: queued, processing, complete, failed. Note the terminal value is complete, not completed.

Consume-once: after a job reaches a terminal state, this status endpoint serves the full result once and may return not-found on later polls. Treat the session read (GET /api/v1/iterate/<session_id>) as the durable record; don't re-poll status after you have the terminal response.

▶ GET /api/v1/iterate/{session_id} Get session state and recommendations

Retrieve the full session state including all iterations, pending recommendations, and the current document.

curl -H "X-API-Key: YOUR_KEY" https://convergeqa.net/api/v1/iterate/YOUR_SESSION_ID
▶ POST /api/v1/iterate/{session_id}/decide Submit decisions and continue or finish

Accept or decline each recommendation, then continue iterating or finish the session.

Parameters:

  • decisions (array, required) - [{"rec_index": 0, "accepted": true, "notes": "..."}, ...]
  • action (string) - "continue", "finish", or "pause"
curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"decisions": [{"rec_index": 0, "accepted": true}, {"rec_index": 1, "accepted": false}], "action": "continue"}' \
  https://convergeqa.net/api/v1/iterate/YOUR_SESSION_ID/decide

On "continue": Returns a new job_id for the next iteration cycle.

On "finish": Finalizes the session and returns the final document.

▶ POST /api/v1/iterate/{session_id}/export Download session as ZIP bundle

Export a completed session as a ZIP file containing the final document, all iteration snapshots, and a decision log.

curl -H "X-API-Key: YOUR_KEY" -o session.zip \
  -X POST https://convergeqa.net/api/v1/iterate/YOUR_SESSION_ID/export
▶ GET /api/v1/iterate/sessions List your iterate sessions

List all iterate and critique sessions for your account.

curl -H "X-API-Key: YOUR_KEY" https://convergeqa.net/api/v1/iterate/sessions
▶ GET /api/v1/audit/{audit_id} Look up audit report

Retrieve audit report metadata by report ID (e.g., CQA-2026-00042).

curl -H "X-API-Key: YOUR_KEY" https://convergeqa.net/api/v1/audit/CQA-2026-00042
▶ GET /api/v1/audit/{audit_id}/documents/{doc_type} Download audit documents

Download documents for a specific audit report.

curl -H "X-API-Key: YOUR_KEY" -o audit.pdf \
  https://convergeqa.net/api/v1/audit/CQA-2026-00042/documents/audit-report.pdf
ConvergeQA uses production-stable versions of each model. Models are updated as new versions reach general availability and demonstrate consistent performance. Specific model versions are recorded with each review when available.
Sensitive Data Notice - ConvergeQA is a document review and quality-assurance platform. It is not a HIPAA-covered service. Do not submit PHI, patient identifiers, secrets, or sensitive regulated data. Users are responsible for de-identifying content before submission.