Docs

Home All sections Swagger

Submissions endpoint

List, create, fetch, and cancel submissions.

Last updated June 3, 2026

A submission is a job you ask Vilvik to run. The endpoint base path is https://beta.vilvik.com/api/v1/submissions/.

Using the Python SDK?

Every operation on this page is available on client.submissions. See Submissions.

List your submissions

GET /api/v1/submissions/?page_size=20

Returns a cursor-paginated array. Pass ?cursor=<value> (taken from the previous response) to get the next page.

curl -H "Authorization: Bearer $VILVIK_KEY" \
     "https://beta.vilvik.com/api/v1/submissions/?page_size=20"

{
  "results": [
    {
      "id": "abcDEF123456",
      "name": "smoke test",
      "status": "succeeded",
      "source": "api",
      "created_at": "2026-05-01T12:34:56Z"
    }
  ],
  "next": "?cursor=...",
  "previous": null
}

Filtering by status, date range, name, and more is documented in Filtering submissions and results.

Required scope: submissions:read.

SDK equivalent: client.submissions.list(...) and client.submissions.iter_all(...). See Submissions.

Create a submission

POST /api/v1/submissions/
Content-Type: application/json

The body carries the same parameters you would set in the website's new-submission form: num_generations, sol_per_pop, num_genes, num_parents_mating, init_range_low, init_range_high, fitness_func (a Python source string), and any optional callbacks.

Every code field needs a companion entry symbol: the top-level name in your source the runtime should call. Send it under <field>_entry, so inline fitness_func source pairs with fitness_func_entry, on_generation with on_generation_entry, and so on. The website auto-fills this from your code; over the API you set it yourself. A code field sent without its entry symbol is rejected with a 422.

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

The response is 202 Accepted with the new id and URLs you can poll:

{
  "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"
}

The optional Idempotency-Key header lets you safely retry the same request without creating a duplicate submission. Use a fresh UUID per distinct submission. If the same key is reused within 24 hours, the server returns the original response instead of running the job again.

Required scope: submissions:write.

SDK equivalent: client.submissions.create(...). See Submissions.

Fetch a single submission

GET /api/v1/submissions/<id>

Returns the full submission row, including current status and timing.

Required scope: submissions:read.

SDK equivalent: client.submissions.get(id). See Submissions.

Cancel or delete a submission

DELETE /api/v1/submissions/<id>

A single DELETE removes the submission. If it is still queued or running, the worker is stopped first, then the row is deleted. Credits already spent on a partial run are still billed. The response is 204 No Content.

curl -X DELETE https://beta.vilvik.com/api/v1/submissions/abcDEF123456 \
  -H "Authorization: Bearer $VILVIK_KEY"

Required scope: submissions:write.

SDK equivalent: client.submissions.delete(id). See Submissions.

Thanks for the feedback!