Runners API Endpoints

Manage runners for executing containerized tasks with our API

Runners allow you to execute containerized tasks on Nodion's infrastructure on demand. Each runner defines a Docker image, a run command, and resource constraints. You can trigger individual runs, pass environment variables, and retrieve logs for each execution.

Get Runners

To list all runners of your project you can simply send a GET request to the following endpoint.

https://api.nodion.com/v1/runners

Required Headers: Authorization

Example Response:

{
  "runners": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "available",
      "name": "Database Backup",
      "image_name": "mycompany/backup-tool",
      "image_tag": "latest",
      "run_command": "python backup.py",
      "argv": [],
      "entrypoint": null,
      "timeout_seconds": 3600,
      "warmed_at": null,
      "created_at": "2026-01-15T10:00:00.000+01:00",
      "updated_at": "2026-01-15T10:00:00.000+01:00",
      "region": {
        "id": "428d037e-9ba6-4dab-92bd-8d816c523126",
        "status": "available",
        "name": "Frankfurt, DE",
        "slug": "fra"
      },
      "instance_type": {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "Standard S",
        "slug": "standard-s",
        "cpu": 1,
        "mem": 1024,
        "price_month": 5.0,
        "price_second": 0.0000019
      },
      "container_registry": null
    }
  ]
}

Get Runner

To fetch a single runner you can simply send a GET request to the following endpoint.

https://api.nodion.com/v1/runners/:id

Required Headers: Authorization

Example Response:

{
  "runner": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "available",
    "name": "Database Backup",
    "image_name": "mycompany/backup-tool",
    "image_tag": "latest",
    "run_command": "python backup.py",
    "entrypoint": null,
    "timeout_seconds": 3600,
    "warmed_at": "2026-01-15T10:00:30.000+01:00",
    "created_at": "2026-01-15T10:00:00.000+01:00",
    "updated_at": "2026-01-15T10:00:30.000+01:00",
    "region": {
      "id": "428d037e-9ba6-4dab-92bd-8d816c523126",
      "status": "available",
      "name": "Frankfurt, DE",
      "slug": "fra"
    },
    "instance_type": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Standard S",
      "slug": "standard-s",
      "cpu": 1,
      "mem": 1024,
      "price_month": 5.0,
      "price_second": 0.0000019
    },
    "container_registry": null
  }
}

Create a Runner

To create a new runner you can simply send a POST request to the following endpoint.

https://api.nodion.com/v1/runners

Required Headers: Authorization

Required Body Parameters:

name – A name for this runner (3-50 characters).

image_name – The Docker image name (e.g. mycompany/backup-tool).

image_tag – The Docker image tag (e.g. latest, v1.0.0).

region_id – The ID of the region where the runner should execute.

instance_type_id – The ID of the instance type that defines CPU and memory limits.

You must provide either argv or run_command, not both:

argv – An array of strings executed in exec form, without a shell wrap. Recommended for SDK and programmatic callers (no shell-injection risk, no quoting hell). Example: ["python", "script.py", "--env", "staging"]. Max 200 elements, total length max 8000 characters.

run_command – A single shell command executed via sh -c (max 1000 characters). Use this when you need shell features like &&, pipes, glob expansion or variable interpolation.

Optional Body Parameters:

entrypoint – A custom entrypoint for the container (max 500 characters).

timeout_seconds – Maximum execution time in seconds (1-86400). Defaults to 3600 (1 hour).

container_registry_id – The ID of a container registry to authenticate when pulling the image.

Possible Response Codes:

200 – The runner was created successfully.
400 – There was something wrong. Please check the response.

Update a Runner

To update an existing runner you can simply send a PATCH request to the following endpoint.

https://api.nodion.com/v1/runners/:id

Required Headers: Authorization

Optional Body Parameters:

name – A new name for the runner.

image_name – A new Docker image name.

image_tag – A new Docker image tag.

argv – A new argv array (exec form). Pass [] to clear it and fall back to run_command.

run_command – A new shell command.

entrypoint – A new entrypoint.

timeout_seconds – A new timeout in seconds (1-86400).

instance_type_id – A new instance type.

region_id – A new region.

container_registry_id – A new container registry.

Possible Response Codes:

200 – The runner was updated successfully.
400 – There was something wrong. Please check the response.

Delete a Runner

To delete a runner you can simply send a DELETE request to the following endpoint.

https://api.nodion.com/v1/runners/:id

Required Headers: Authorization

Possible Response Codes:

200 – The runner was deleted successfully.
400 – There was something wrong. Please check the response.

Warm up a Runner

Warming a runner pre-pulls the container image onto a hypervisor in the runner's region and pins that hypervisor as the preferred target for the next run, eliminating the image-pull cost on the first execution. The warmup runs asynchronously in the background.

https://api.nodion.com/v1/runners/:id/warmup

Required Headers: Authorization

Possible Response Codes:

202 – The warmup was accepted and is running in the background.
400 – There was something wrong. Please check the response.

Once the warmup completes, the runner's warmed_at timestamp is set. Poll GET /v1/runners/:id to detect completion. The pinned hypervisor is used for the next run if it still has free capacity. Otherwise Nodion falls back to picking any hypervisor with available memory.

Example Response:

{
  "success": true
}