API Docs

External review API for organizations that want to use VeracityGXP agents from their own systems.

The external API is Bring Your Own Key (BYOK) only. Your system authenticates with a Veracity workspace API key, and VeracityGXP executes reviews using your workspace's enabled AI provider key.

1. Authenticate

Call the API with a workspace API key in the `Authorization` header.

2. Choose agent + key

List enabled agents, then include the correct `providerKeyId` when multiple customer keys are enabled.

3. Submit + retrieve

Submit review text, then poll or stream progress, findings, and chat/report output until completion.

Authentication model

The external API uses a Veracity workspace API key for authorization. This key identifies the calling workspace.

Review execution still uses the customer's own enabled AI provider key from the workspace. Managed Evaluation allowance is not available over the external API.

A workspace can store multiple named provider keys from the same provider. If more than one enabled key exists, the submit request must include `providerKeyId`.

In the browser app, multi-key BYOK routing is handled by selecting a workspace default provider key in Provider Keys.

Authorization: Bearer vgxp_your_workspace_api_key

x-veracity-api-key: vgxp_your_workspace_api_key

Provider key management

Workspaces can manage provider keys over API as well as the browser UI. This lets headless integrations add multiple named keys for different downstream customers before submitting reviews.

`PATCH /api/workspace/provider-keys/:providerKeyId` also supports `setAsDefault: true` for in-app review routing.

Authenticated workspace API keys can call:

`GET /api/workspace/provider-keys`
`POST /api/workspace/provider-keys`
`PATCH /api/workspace/provider-keys/:providerKeyId`
`DELETE /api/workspace/provider-keys/:providerKeyId`

Endpoints

GET /api/external/agents

List enabled review agents for the authenticated workspace.

POST /api/external/reviews

Create a BYOK-only external review from pasted text and optionally target a specific `providerKeyId`.

GET /api/external/reviews/:reviewId

Read current status, selected agent, summary, and endpoint references.

GET /api/external/reviews/:reviewId/events

Read progress narration and job timeline events.

GET /api/external/reviews/:reviewId/findings

Read structured findings.

GET /api/external/reviews/:reviewId/chat

Read the report transcript, including status narration, findings, and summary messages.

GET /api/external/reviews/:reviewId/stream

Receive review snapshot and incremental updates over Server-Sent Events (SSE).

1. List agents

curl -H "Authorization: Bearer vgxp_your_workspace_api_key" \
  https://veracity-gxp.vercel.app/api/external/agents

2. Submit a review

curl -X POST https://veracity-gxp.vercel.app/api/external/reviews \
  -H "Authorization: Bearer vgxp_your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Protocol excerpt review",
    "reviewAgentId": "agent_uuid_here",
    "providerKeyId": "provider_key_uuid_here",
    "clientReference": "protocol-42",
    "text": "Paste the document text here..."
  }'

3. Poll status

curl -H "Authorization: Bearer vgxp_your_workspace_api_key" \
  https://veracity-gxp.vercel.app/api/external/reviews/review_uuid_here

4. Stream updates

curl -N -H "Authorization: Bearer vgxp_your_workspace_api_key" \
  https://veracity-gxp.vercel.app/api/external/reviews/review_uuid_here/stream

Error model

Errors return machine-readable codes so integrations can handle them safely.

{
  "error": {
    "code": "provider_key_selection_required",
    "message": "Multiple enabled provider keys exist for this workspace. Submit providerKeyId to route the review to the correct customer key.",
    "details": {
      "enabledProviderKeys": [
        {
          "id": "provider_key_uuid_here",
          "name": "Acme EU OpenAI",
          "provider": "openai",
          "model": "gpt-4.1-mini"
        }
      ]
    }
  }
}