API Reference | Versalist Documentation

Scoped keys authenticate challenge workflows outside the browser through the x-api-key header. The live API-key surface focuses on the challenge loop: browsing, exports, and submissions. Most users should begin with the CLI unless they are wiring direct automation, and the related route /docs/api-keys is where you create and scope the platform keys before using these endpoints.

This is a focused API surface, not a generic everything API. The current Versalist API-key surface is deliberately centered on the challenge loop: list challenges, load details and markdown, inspect gold items or leaderboard context, and create submissions. That makes it useful for CLI and automation without pretending every product surface is already equally programmable. Open CLI docs.

What this API is for

Use the API when you want challenge data or submission workflows inside a script, local tool, editor integration, or CI-like automation loop. If you only want to browse or start a challenge from the terminal, the CLI is usually the better first abstraction.

List and load challenge content

Fetch listings, detail pages, markdown exports, gold items, and leaderboard context from non-browser workflows.

Create submissions

Post challenge submissions from local tools or agent workflows when a browser session is not the right auth model.

Support CLI and MCP

The API is the underlying surface that powers the CLI and related editor or agent integrations. Open CLI docs.

Authentication

Create a scoped key in API Keys, then send it in the x-api-key header. These are user-scoped platform keys, which means they are appropriate for your own tooling and automation environment.

fetch('https://versalist.com/api/challenges', {
  headers: {
    'x-api-key': 'vk_live_...',
    'Content-Type': 'application/json'
  }
})

read:challenges

Browse challenge lists, load challenge details, export markdown, and read public gold items or leaderboard context.

submit:solutions

Create challenge submissions from local tooling or an automation surface.

read:submissions

Inspect your own submission history and related statuses when the workflow needs it.

Current endpoints

These are the routes that matter most for the current API-key surface. Treat them as the live challenge automation contract rather than expecting a broader general-purpose product API today.

Endpoint	Purpose	Required scope
`GET /api/challenges`	List published challenges.	`read:challenges`
`GET /api/challenges/:id-or-slug`	Load challenge detail.	`read:challenges`
`GET /api/challenges/:id-or-slug/markdown`	Export the challenge brief as markdown.	`read:challenges`
`GET /api/challenges/:id-or-slug/gold-items`	Read public reference items.	`read:challenges`
`GET /api/challenges/:id-or-slug/leaderboard`	Inspect leaderboard context.	`read:challenges`
`POST /api/challenges/submissions`	Create a challenge submission.	`submit:solutions`
`GET /api/user/submissions`	Read your own submission history.	`read:submissions`

CLI and MCP

For most users, the best API experience is still the Versalist CLI. It wraps the same authenticated challenge workflows and removes a lot of unnecessary implementation detail when your real goal is “start the challenge” or “submit the run”.

export VERSALIST_API_KEY=vk_live_...
versalist start dspy-optimization-challenge
versalist mcp

Create the scoped platform key. Start by defining the smallest auth surface your tooling actually needs. Create a key.
Choose CLI versus direct API. Use the CLI for most human workflows and direct HTTP only when you are wiring custom automation. Compare with the CLI.
Read and export challenge context. Challenge detail, markdown, gold items, and leaderboard routes are what make the API useful for local automation.
Submit from the same loop. Post the challenge submission only after the repo, prompt, or agent workflow already has the right context attached.

What is still expanding

Versalist is continuing to expand the programmable surface beyond the challenge loop. The right assumption today is that the challenge workflow is the stable core, while broader API coverage across the product continues to evolve.

The fastest next reads are API Keys for creation and scope design, then CLI for the higher-level interface most users should adopt before they wire direct HTTP.

Documentation