Runners API Endpoints

Manage runners for executing containerized tasks with our API

Runners allow you to execute one-off or scheduled containerized tasks on Nodion's infrastructure. 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.

Contents

GET /runners
GET /runners/:id
POST /runners
PATCH /runners/:id
DELETE /runners/:id

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",
      "entrypoint": null,
      "timeout_seconds": 3600,
      "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,
    "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
  }
}

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).

run_command – The command to execute inside the container (max 1000 characters).

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.

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.

run_command – A new run 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.