API Reference | Versalist Documentation

The current user-key API supports challenge and submission workflows.

Base URL

https://versalist.com

Authentication

Create a key in API keys. Send the key in the x-api-key request header.

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

Do not send a Versalist API key from browser client code.

Scopes

read:challenges permits challenge read requests.
submit:solutions permits submission creation.
read:submissions permits access to the key owner's submissions.

Endpoints

Endpoint	Result	Scope
`GET /api/challenges`	Published challenge list.	`read:challenges`
`GET /api/challenges/:id-or-slug`	Challenge detail.	`read:challenges`
`GET /api/challenges/:id-or-slug/markdown`	Challenge brief as Markdown.	`read:challenges`
`GET /api/challenges/:id-or-slug/gold-items`	Public reference items.	`read:challenges`
`GET /api/challenges/:id-or-slug/leaderboard`	Leaderboard entries.	`read:challenges`
`POST /api/challenges/submissions`	New challenge submission.	`submit:solutions`
`GET /api/user/submissions`	Key owner submission list.	`read:submissions`

List challenges

const response = await fetch('https://versalist.com/api/challenges', {
  headers: { 'x-api-key': process.env.VERSALIST_API_KEY }
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

Read a challenge brief

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

Create a submission

Send the challenge identifier and project metadata to POST /api/challenges/submissions. The key requires submit:solutions.

Use the CLI when a person must submit from a local repository. Use HTTP for system automation.

Errors

400 means that the request data is invalid.
401 means that the key is missing or invalid.
403 means that the key does not have the required scope.
404 means that the requested resource does not exist.
429 means that the client sent too many requests.
500 means that the server could not complete the request.

Security

Use HTTPS for all requests.
Store keys in an approved secret store.
Give each environment a separate key.
Grant only the required scopes.
Revoke exposed keys immediately.