Docs

Home All sections Swagger

API overview

What the public REST API does and how requests and responses are shaped.

Last updated June 3, 2026

Go to the live page Open the API playground

The public REST API lets your code submit jobs, read results, and receive webhooks when runs finish. Anything you can do from the website can be done from a script.

Writing Python? Use the SDK

The official vilvik Python package wraps every endpoint on this page. See Python SDK overview to install it. The REST pages stay accurate for other languages and for understanding what the SDK does under the hood.

API usage is credit-based, your account holds a balance, and each submission deducts credits at the time it runs. There is no monthly fee on the API side. See Credits for how the balance works and Rate limits and quotas for the throughput and concurrency limits that apply to API traffic.

Base URL

https://beta.vilvik.com/api/v1

This same URL works for both the local server and the production site. Every example on these pages uses it directly so you can copy a curl command without editing anything.

Versioning

The current version is v1. We will only break behaviour when we bump to a new major version. Smaller, additive changes (new optional fields, new endpoints) ship inside v1.

How requests look

Every request needs an Authorization: Bearer <key> header. JSON bodies are sent with Content-Type: application/json.

curl -X POST https://beta.vilvik.com/api/v1/submissions \
  -H "Authorization: Bearer $VILVIK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"smoke test","num_generations":10,"sol_per_pop":4,"num_genes":3,"num_parents_mating":2,"init_range_low":-1,"init_range_high":1,"fitness_func":"def fitness_func(ga, sol, idx): return sum(sol)\n","fitness_func_entry":"fitness_func"}'

For ready-made recipes covering every common task (listing, fetching, cancelling, results, continuing a run, and more), see API examples.

How responses look

Every successful response is JSON. Endpoints that create a job return 202 Accepted with a body that includes the new submission's id and URLs you can poll. Endpoints that list rows return a cursor-paginated object.

{
  "id": "abcDEF123456",
  "status": "queued",
  "status_url": "https://beta.vilvik.com/api/v1/submissions/abcDEF123456",
  "result_url": "https://beta.vilvik.com/api/v1/results?submission_id=abcDEF123456"
}

How errors look

Errors return a non-2xx status with a JSON body that includes a machine-readable code and a human message. See Errors for the full list.

The request lifecycle

Here is what happens between your call and the response:

sequenceDiagram participant Your as Your code participant API as Vilvik API participant Q as Job queue participant W as Worker participant Hook as Your webhook URL Note over Your,API: Accept phase (fast, synchronous) Your->>API: POST /api/v1/submissions API->>API: Auth, scope check, credit check opt Quick submission type API->>API: Quick builder fills defaults and fitness code end API->>Q: Enqueue API-->>Your: 202 Accepted (id, status_url, generated) Note over Q,W: Run phase (asynchronous) Q->>W: Dispatch W->>W: Run in secure environment Note over W: Credits deducted from actual compute used W-->>API: Save result Note over Your,Hook: Notify phase (push or pull) alt You registered a webhook API->>Hook: POST result.completed Hook-->>API: 2xx, retried with back off if not else You poll instead Your->>API: GET status_url API-->>Your: status succeeded, result_url end

In words: the API answers immediately with an id so your code does not have to wait. The job runs on a worker, credits are deducted from the compute the run actually used, and you find out it is done either by polling the status URL or by receiving a webhook. The wider picture is in How Vilvik works.

Where to go next

Thanks for the feedback!