API Reference

Auth header

x-api-key

Scoped keys authenticate challenge workflows outside the browser.

Current surface

Challenge loop

The live API-key routes focus on challenge browsing, exports, and submissions.

Best entry point

CLI first

Most users should begin with the CLI unless they are wiring direct automation.

Related route

/docs/api-keys

Create and scope the platform keys before using these endpoints.

Current product shape

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.

Programmatic browse

List and load challenge content

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

Authenticated execution

Create submissions

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

Tooling surface

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'
  }
})

Scope

read:challenges

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

Scope

submit:solutions

Create challenge submissions from local tooling or an automation surface.

Scope

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

What this API is for

Authentication

Current endpoints

CLI and MCP

What is still expanding

Related docs