⌘K

API Keys

Generate, configure, and revoke API keys for programmatic access to AskVerdict.

7 min read

API keys authenticate your requests to the AskVerdict REST API. You can generate multiple keys, each with its own name and optional configuration (model preset, routing overrides, provider restrictions, and rate limits).

Base URL

All endpoints below are relative to https://api.askverdict.ai. Managing API keys requires an active session (cookie-based auth via the dashboard) or an existing API key.

Keys are shown once

The full API key value is returned only at creation time and is never retrievable again. Store it securely immediately after generation. If a key is lost, revoke it and generate a new one.

Endpoints

Method	Path	Description
`POST`	`/api/keys`	Generate a new API key
`GET`	`/api/keys`	List your active API keys
`PATCH`	`/api/keys/:id`	Update a key's name or configuration
`DELETE`	`/api/keys/:id`	Revoke an API key

POST /api/keys

POST/api/keys

Generate a new API key. Returns the full key value (prefixed with vrd_) exactly once — store it immediately as it cannot be retrieved after this response.

Request Body

Name	Type	Required	Description
`name`	`string`	Required	A human-readable label for this key. 1–100 characters. Used to identify keys in the dashboard and list endpoint.
`config`	`object`	Optional	Optional key-level configuration that overrides account defaults for requests made with this key. See Config Object below.

Config Object

Name	Type	Required	Description
`config.preset`	`"balanced" \| "economy" \| "hackathon" \| "local" \| "custom"`	Optional	Named model configuration preset applied to debates run with this key.
`config.routingOverrides`	`Record<TaskType, Tier \| null>`	Optional	Per-task model tier overrides. Provide a map of task name → tier or null (disabled). See task types below.
`config.allowedProviders`	`string[]`	Optional	Restrict which AI providers this key is permitted to use. Valid values: anthropic, openai, google, ollama, openrouter. Minimum 1 if provided.
`config.rateLimit`	`integer \| null`	Optional	Per-minute request rate limit for this key. Null for no key-level limit (account limits still apply).
`config.description`	`string`	Optional	Internal notes about this key's purpose. Maximum 500 characters.

Task Types (for routingOverrides)

Task	Description
`orchestrator`	Coordinates the overall debate flow
`synthesizer`	Produces the final verdict and summary
`debater`	Individual AI agent debate participants
`classifier`	Classifies argument types and fallacies
`search_planner`	Plans and executes web searches
`mid_debate_analyst`	Analyses debate progress between rounds
`fact_checker`	Verifies factual claims
`controversy_scorer`	Scores argument controversy

Model Tiers

Tier	Description
`opus`	Largest, most capable models
`sonnet`	Balanced performance and cost
`haiku`	Fast and economical
`local`	Self-hosted models via Ollama

Example Requests

bash

# Basic key with a name
curl -X POST https://api.askverdict.ai/api/keys \
  -H "Authorization: Bearer vrd_existing_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production App" }'
 
# Key with configuration — economy preset, restricted to Anthropic only
curl -X POST https://api.askverdict.ai/api/keys \
  -H "Authorization: Bearer vrd_existing_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cost-Optimised Worker",
    "config": {
      "preset": "economy",
      "allowedProviders": ["anthropic"],
      "rateLimit": 10,
      "description": "Worker process key — cost-capped for batch jobs"
    }
  }'
 
# Key with routing overrides — use haiku for debaters, sonnet for synthesizer
curl -X POST https://api.askverdict.ai/api/keys \
  -H "Authorization: Bearer vrd_existing_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fast Debater Config",
    "config": {
      "routingOverrides": {
        "debater": "haiku",
        "synthesizer": "sonnet",
        "orchestrator": "sonnet"
      }
    }
  }'

Response

Key prefix

The keyPrefix (e.g. vrd_live_a1b2) is always available — use it to identify which key a request was made with in your logs without ever logging the full key value.

GET /api/keys

GET/api/keys

List all active API keys for your account. Key hashes and full values are never returned — only the prefix and configuration.

Example Requests

bash

curl "https://api.askverdict.ai/api/keys" \
  -H "Authorization: Bearer vrd_your_api_key"

Response

PATCH /api/keys/:id

PATCH/api/keys/:id

Update a key's name or configuration. The key value itself cannot be changed — to rotate a key, revoke the old one and generate a new one.

Key rotation

AskVerdict does not support in-place key rotation (changing the key value). To rotate a key: generate a new key first with the same configuration, update your application to use the new key, then revoke the old one. This approach ensures zero-downtime rotation.

Path Parameters

Name	Type	Required	Description
`id`	`string`	Required	The API key ID (not the key value — use the id from the list endpoint).

Request Body

Name	Type	Required	Description
`name`	`string`	Optional	New display name for the key. 1–100 characters.
`config`	`object`	Optional	Replacement config object. The entire config is replaced, not merged — supply all config fields you want to keep.

Example Requests

bash

# Rename a key
curl -X PATCH "https://api.askverdict.ai/api/keys/key_7f3e2a1b" \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production App v2" }'
 
# Update config — add rate limit
curl -X PATCH "https://api.askverdict.ai/api/keys/key_7f3e2a1b" \
  -H "Authorization: Bearer vrd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "preset": "economy",
      "allowedProviders": ["anthropic", "openai"],
      "rateLimit": 5,
      "description": "Tightened rate limit for cost control"
    }
  }'

Response

Error Responses

Status	Code	Description
`400`	`VALIDATION_ERROR`	Name is empty, config is invalid, or `allowedProviders` has zero entries
`403`	`FORBIDDEN`	Key belongs to a different account
`404`	`NOT_FOUND`	Key not found or already revoked

DELETE /api/keys/:id

DELETE/api/keys/:id

Revoke an API key permanently. Any requests using the revoked key will immediately receive 401 Unauthorized. This action cannot be undone.

Path Parameters

Name	Type	Required	Description
`id`	`string`	Required	The API key ID to revoke.

Example Requests

bash

curl -X DELETE "https://api.askverdict.ai/api/keys/key_7f3e2a1b" \
  -H "Authorization: Bearer vrd_your_api_key"

Good name	Why
`Production API — web app`	Identifies service and environment
`CI/CD pipeline`	Easy to revoke if a workflow is compromised
`Developer: Alice Chen`	Per-person keys allow targeted revocation

Least-Privilege Configuration

Use the config object to restrict what each key can do:

json

{
  "allowedProviders": ["anthropic"],
  "rateLimit": 10,
  "preset": "economy"
}

This key can only use Anthropic models, is capped at 10 requests per minute, and always uses the economy model preset — limiting blast radius if the key is ever compromised.

Rotation Schedule

Rotate keys at least every 90 days for production environments. The zero-downtime rotation process:

Generate a new key with POST /api/keys
Deploy the new key to your application
Verify requests are succeeding with the new key
Revoke the old key with DELETE /api/keys/:id

Key Leak Response

If a key is leaked (committed to git, logged in plaintext, exposed in error messages):

Immediately revoke the compromised key via DELETE /api/keys/:id
Generate a replacement key and deploy it
Audit recent usage in the developer portal for any unauthorised activity
Check your account's debate history for unexpected usage

API Key Object Reference

Field	Type	Description
`id`	`string`	Internal key identifier (not the key value)
`name`	`string`	Human-readable label
`keyPrefix`	`string`	First ~16 characters of the key — safe to log and display
`config`	`ApiKeyConfig \| null`	Optional key-level configuration
`createdAt`	`string (ISO 8601)`	When the key was generated

ApiKeyConfig Object

Field	Type	Description
`preset`	`string \| null`	Named model preset
`routingOverrides`	`Record<string, string \| null> \| null`	Per-task tier overrides
`allowedProviders`	`string[] \| null`	Permitted AI providers
`rateLimit`	`integer \| null`	Per-minute request cap for this key
`description`	`string \| null`	Internal notes

Was this page helpful?

PreviousScheduled Debates API NextAPI User Profile

API Keys

Endpoints

POST /api/keys

Request Body

Config Object

Task Types (for routingOverrides)

Model Tiers

Example Requests

Response

GET /api/keys

Example Requests

Response

PATCH /api/keys/:id

Path Parameters

Request Body

Example Requests

Response

Error Responses

DELETE /api/keys/:id

Path Parameters

Example Requests

Response

Security Best Practices

Key Naming Strategy

Least-Privilege Configuration

Rotation Schedule

Key Leak Response

API Key Object Reference

ApiKeyConfig Object

Product

Company

Use Cases

Teams

Content

Developer

Policies

Agreements