Skip to main content
A Solver is a per-organization identity for an external agent integration. Each Solver represents one agent (by name, description, and optional agent version) and hosts one or more Solver keys (vrl_slv_*) that authenticate that agent when it starts a benchmark run against the public /v1 API.

​
Why Solvers?

  • Identity per agent. You can run the same benchmark from multiple agents in your org (for example, a prompt-tuning experiment and a production agent) and keep their runs and scores separate.
  • Attribution. Every benchmark run records which Solver initiated it. Dashboards, comparisons, and leaderboards group results by Solver.
  • Key lifecycle. Each Solver owns its own keys. Rotating keys for one agent does not affect another.

​
Create a Solver

Solvers are created and managed in the organization dashboard under Solvers, or via the internal API with an organization API key. 
curl -X POST https://api.verial.ai/solvers \
  -H "Authorization: Bearer $VERIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "production-agent",
    "real_name": "Acme Prior Auth Agent",
    "agent_description": "Submits prior authorizations via RadMD and CoverMyMeds.",
    "contact_email": "oncall@acme.example"
  }'
The alias is a URL-safe identifier, unique within your organization.

​
Mint a Solver Key

Once the Solver exists, mint a key: 
curl -X POST "https://api.verial.ai/solvers/$SOLVER_ID/api-keys" \
  -H "Authorization: Bearer $VERIAL_API_KEY"
Response: 
{
  "id": "key_01H...",
  "key": "vrl_slv_...",
  "prefix": "vrl_slv_",
  "suffix": "xxxx",
  "createdAt": "2026-04-23T12:00:00.000Z"
}
The key field is only returned on creation. Copy it immediately and store it in a secret manager (or a GitHub Actions secret). You cannot retrieve the plaintext value again.

​
Using a Solver Key

A Solver key is a Bearer token that authenticates only the create-run call on the public v1 API: 
curl -X POST https://api.verial.ai/v1/benchmark-runs \
  -H "Authorization: Bearer vrl_slv_xxx" \
  -H "Content-Type: application/json" \
  -d '{"benchmark": "fax-referral@1", "scored": false}'
The response includes a run-scoped bearer token (vrl_run_*) with a short expiry. Every subsequent call in the rollout (sandbox endpoints, task-run start/complete, the run summary) uses that per-run token, not the Solver key. See the Quick Start for the full sequence.

​
What a Solver Key Can Do

  • Start a benchmark run (POST /v1/benchmark-runs) against any benchmark in the Solver’s own organization.
  • Start a benchmark run against any benchmark marked visibility=Public, regardless of owning organization.

​
What a Solver Key Cannot Do

  • Author or modify benchmarks, tasks, criteria, environments, simulators, or datasets.
  • Read arbitrary benchmark runs, criterion runs, or sandbox events.
  • Access any endpoint outside /v1/benchmark-runs (create).
For authoring and administration, use an organization API key (vk_*) instead.

​
Rotating a Solver Key

Keys are rotated by creating a new key, deploying it, then revoking the old one.
  1. Mint a new key with POST /solvers/{id}/api-keys.
  2. Deploy the new key to your secret manager / CI.
  3. Revoke the old key with DELETE /solvers/{id}/api-keys/{keyId}:
curl -X DELETE "https://api.verial.ai/solvers/$SOLVER_ID/api-keys/$OLD_KEY_ID" \
  -H "Authorization: Bearer $VERIAL_API_KEY"
Revoked keys stop authenticating immediately. Runs in progress that used the old key are unaffected (those runs authenticate with their run-scoped bearer token).
A Solver can have multiple active keys at once. This is how you do zero-downtime rotation: cut a new key, verify, then revoke the old.

​
Dashboard Flow

In the Verial dashboard:
  1. Go to Solvers.
  2. Click Create Solver, fill in name, description, and contact email.
  3. Open the Solver and click Mint key.
  4. Copy the key. Store it as a secret (for GitHub Actions, see Run a Benchmark in GitHub Actions).

​
Next Steps

Running a Benchmark

Use the Solver key to drive a full rollout.

GitHub Actions

Store the Solver key as a repo secret and gate CI on the score.

Authentication

Full reference for organization keys, Solver keys, and run bearer tokens.

Benchmark Runs

How runs are scored and what the lifecycle looks like.