API reference

Base URL: https://versalist.com. Override it in the CLIs with VERSALIST_BASE_URL.

First request

No key. Public catalog only.

curl "https://versalist.com/api/challenges/public?limit=5"

Response shape: { data: Challenge[], pagination }. Default limit is 20, max 100.

Authentication

Create a key on Developer API. Send it on every authenticated request:

curl "https://versalist.com/api/challenges?limit=5" \
  --header "x-api-key: $VERSALIST_API_KEY"

Live keys start with vk_live_. Test keys start with vk_test_. Do not send a key from browser JavaScript.

Scopes

Skill scopes are for vskill and /api/skills/registry/*. Challenge routes do not accept them as a substitute for the challenge scopes. The run and governance scopes are explained on API keys; note that the key creation page does not list them yet.

Two kinds of authentication appear below. key means an x-api-key header with the named scope. session means a signed-in browser session; these routes do not accept API keys, and non-GET calls must be same-origin. This is how the web app calls them.

Endpoints

:id-or-slug accepts a UUID or a slug. POST /api/challenges/submissions does not — challenge_id must be the UUID.

GET /api/challenges/public

Anonymous catalog. This is what versalist list calls when VERSALIST_API_KEY is unset.

curl "https://versalist.com/api/challenges/public?search=reranker&limit=10"

{
  "data": [
    {
      "id": "…",
      "slug": "agentic-code-optimization-review",
      "title": "Agentic code optimization review",
      "brief_description": "…",
      "category": "evaluation",
      "difficulty": "advanced",
      "tags": ["agents"],
      "timeEstimate": "2h",
      "participantsCount": 12,
      "runsSubmitted": 40
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 4,
    "totalItems": 37,
    "limit": 10
  }
}

GET /api/challenges

Authenticated list. Includes public and unlisted challenges visible to the key owner. Session requests (no key) default limit to 8; the key path defaults to 20. Both clamp at 50 — not 100.

const response = await fetch('https://versalist.com/api/challenges?limit=20', {
  headers: { 'x-api-key': process.env.VERSALIST_API_KEY }
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

{
  "challenges": [
    {
      "id": "…",
      "slug": "agentic-code-optimization-review",
      "title": "Agentic code optimization review",
      "description": "…",
      "difficulty": "advanced",
      "category": "evaluation",
      "points": 100,
      "timeEstimate": "2h",
      "tags": ["agents"],
      "featured": false,
      "createdAt": "2026-01-15T00:00:00.000Z"
    }
  ],
  "totalCount": 37,
  "page": 1,
  "limit": 20
}

GET /api/challenges/:id-or-slug

Challenge detail, including overview, rules, objectives, and eval module.

curl "https://versalist.com/api/challenges/agentic-code-optimization-review" \
  --header "x-api-key: $VERSALIST_API_KEY"

200: { challenge: { id, slug, title, description, …, overviewContent, learnContent, rulesContent, objectives, evalModule } }. 404 if the challenge is missing or private to someone else.

GET /api/challenges/:id-or-slug/markdown

curl "https://versalist.com/api/challenges/$CHALLENGE_ID/markdown" \
  --header "x-api-key: $VERSALIST_API_KEY"

{
  "markdown": "# Agentic code optimization review\n\n…",
  "cached": true,
  "generatedAt": "2026-08-30T18:00:00.000Z"
}

GET /api/challenges/:id-or-slug/gold-items

Public reference items for non-creators. 200: { items: GoldItem[] }.

GET /api/challenges/:id-or-slug/leaderboard

GET /api/challenges/:id/submissions

Public leaderboard of submissions by default. Pass user_only=trueto see only the key owner's rows — that path requires read:submissions.

POST /api/challenges/submissions

The write you have to get right. Scope: submit:solutions. Prefer the CLI from a local repo; use HTTP from automation.

curl https://versalist.com/api/challenges/submissions \
  --header "x-api-key: $VERSALIST_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "challenge_id": "11111111-1111-1111-1111-111111111111",
    "project_title": "Candidate run",
    "project_description": "Baseline agent with a tighter review rubric.",
    "project_url": "https://github.com/you/solution",
    "github_url": "https://github.com/you/solution",
    "tags": ["agents", "review"],
    "agent_metadata": {
      "model": "claude-sonnet-4-6",
      "toolchain": "raw",
      "version": "1.0.0"
    }
  }'

201/200: { success: true, submission: { id, challenge_id, project_title, … } }.

409 if this account already submitted to the challenge:

{ "error": "You have already submitted a project for this challenge." }

Resolve a slug to a UUID first:

curl "https://versalist.com/api/challenges/agentic-code-optimization-review" \
  --header "x-api-key: $VERSALIST_API_KEY"

GET /api/user/submissions

The key owner's submissions. Optional query: challenge_id (UUID).

curl "https://versalist.com/api/user/submissions" \
  --header "x-api-key: $VERSALIST_API_KEY"

200: { submissions: [{ id, challenge_id, project_title, …, agent_metadata, challenges: { id, slug, title, difficulty } }] }.

Runs

A run is one recorded agent attempt against a challenge. The API calls it an Episode, and the routes keep that name. Hosted runs are session-authenticated; the run protocol at /api/v1/runs is for a runner on your own machine and takes an API key.

POST /api/episodes

Send an Idempotency-Key header containing a UUID. Repeating the same key returns the existing run with idempotent_replay: true instead of starting a second one.

{
  "id": "…",
  "status": "pending",
  "evaluation_job_id": "…",
  "idempotent_replay": false,
  "comparison_role": "candidate",
  "provenance": {
    "evaluation_scope": "full_suite",
    "execution_origin": "platform",
    "provenance_level": "platform_verified"
  }
}

status moves through pending, running, and then completed, failed, or cancelled. Poll GET /api/episodes/:id; the response shape is annotated on Understand your results.

POST /api/episodes/:id/cancel

{ "id": "…", "status": "cancelled" }
{ "id": "…", "status": "completed", "message": "Episode is not running" }

Cancellation stops further steps. A sandbox execution already in flight ends at its own deadline.

GET /api/v1/runs

{ "status": "ready", "providers": ["ollama", "openai", "anthropic", "google-ai", "openai-compatible"], "protocol_version": "2.0" }

/api/v1/runs is the provider-neutral name for /api/v1/local-runs; both paths serve the same routes. The protocol is feature-flagged: when it is off, every route returns 404 NOT_FOUND. Runs created here are recorded as self_reported and evaluate public cases only. The CLI implements the claim, heartbeat, and result steps for you; see Local model runs.

Environment versions

An environment version is an immutable, digested description of the runtime, verifier, and evaluator a challenge is bound to. Bound runs record its identifier. Comparisons also require matching cases, models, and generation settings.

Publishing requires blueprint.execution.sandbox_type of none, docker, or browser, timeout_seconds 1–300, and a blueprint.executable section that compiles; otherwise 400 VALIDATION_ERROR. Published versions cannot be changed or deleted.

curl https://versalist.com/api/v1/environments/runs \
  --header "x-api-key: $VERSALIST_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "episode_id": "<episode-uuid>",
    "environment_version_id": "<version-uuid>",
    "idempotency_key": "triage-v2-case-1",
    "input": "Subject: Refund not received …"
  }'
# 202 { "job_id": "…" }

Execution records

Saved runs from sweeps and background executions are kept as execution records (the API calls them rollouts, and the collection a corpus). Each record has a status of queued, claimed, running, verifying, completed, failed, or cancelled, plus per-check rewards and a trace summary.

curl "https://versalist.com/api/v1/corpus/failures?from=2026-09-01T00:00:00Z&to=2026-09-08T00:00:00Z&challenge_id=<uuid>" \
  --header "x-api-key: $VERSALIST_API_KEY"

Categories are assertion_failed, timeout, runtime_error, provider_error, policy_denied, invalid_output, and unknown. What each one means, and how retention works, is on Understand your results.

Sweep models must be dated snapshots such as gpt-4.1-2025-04-14; a mutable alias is rejected, and the snapshot must be on the approved list for your workspace (403 Model release is not approved).

Comparisons and release decisions

These routes record the review-and-release workflow described in Test a change before you release it. Reads need read:governance; writes need write:governance. All responses are Cache-Control: private, no-store.

Errors

Challenge routes mostly return { error: "<human sentence>" }. A smaller set (gold-items, some 500s) return the structured envelope { error: "CODE", message, detail? }. Every /api/episodes and /api/v1/* route uses the structured envelope. Read both fields.

{ "error": "project_title must be 200 characters or fewer" }
{ "error": "API key missing required scope: submit:solutions" }
{ "error": "UNAUTHORIZED", "message": "Authentication required" }

Rate limits

Other platform routes (invite activation, email, extension, AI generation) use the limits below. When they reject, some responses include X-RateLimit-Remaining and X-RateLimit-Reset. There is no guaranteed Retry-After header.

Local model runs can return 429 for a separate judge quota. That path is documented on local model runs.

Other authenticated surfaces

• Skill Exchange — /api/skills/registry/*, scopes read:skills / write:skills. Use @versalist/vskill.
• Local runs — /api/v1/local-runs/*, the same routes as /api/v1/runs. Scope submit:solutions, or read:runs / execute:runs. Feature-flagged. Use versalist challenge run.
• MCP tools — same challenge routes, invoked from an editor.

Security

• HTTPS only.
• Store keys in a secret manager. One key per environment.
• Grant only the scopes you use.
• Revoke a leaked key immediately.