Runners

GET/v1/runners

List runners

Returns all registered self-hosted runners for the organization plus an overall readiness summary. Runners authenticate to daemon endpoints with runner tokens; this API-key endpoint is for setup and monitoring.

Example Request

bash

curl -X GET "https://apviso.com/api/v1/runners" \
  -H "X-API-Key: apvk_your_key_here"

Response

Returns runner records with redacted token metadata and a readiness summary.

json

{
  "runners": [
    {
      "id": "runner-1",
      "name": "prod-runner-1",
      "tokenPrefix": "a1b2c3d4e5f6",
      "status": "online",
      "version": "0.1.0",
      "containerEngine": "docker",
      "configuredConcurrency": 1,
      "currentJobs": 0,
      "providerState": {
        "modelProvider": "openai-codex",
        "embeddingProvider": "local"
      },
      "capabilities": {
        "localProviderSecrets": true,
        "localTargetAuthConfig": true
      },
      "lastHeartbeatAt": "2026-05-03T09:15:32Z"
    }
  ],
  "readiness": {
    "ready": true,
    "visibilityOk": true,
    "runnerOk": true,
    "selectedRunnerId": "runner-1",
    "license": {
      "plan": "team",
      "licenseState": "active",
      "runnerLimit": 10,
      "concurrentJobLimit": 10,
      "targetLimit": 25,
      "allowedTargetVisibilities": [
        "public",
        "staging_preview",
        "private_internal",
        "localhost"
      ]
    },
    "runners": [
      {
        "id": "runner-1",
        "name": "prod-runner-1",
        "status": "online"
      }
    ]
  }
}

GET/v1/runners/readiness

Get runner readiness

Checks whether the current license, optional target visibility, optional selected runner, and runner heartbeats allow a self-hosted scan to start.

Query Parameters

Name	Type	Description
`targetId`	`string`	Optional target ID to include target visibility checks.
`runnerId`	`string`	Optional runner ID to require a specific online runner.

Example Request

bash

curl -X GET "https://apviso.com/api/v1/runners/readiness" \
  -H "X-API-Key: apvk_your_key_here"

Response

Returns readiness booleans, license details, and eligible runners.

json

{
  "ready": true,
  "visibility": "private_internal",
  "visibilityOk": true,
  "runnerOk": true,
  "selectedRunnerId": "runner-1",
  "license": {
    "plan": "team",
    "licenseState": "active",
    "canRegisterRunner": true,
    "canStartSelfHostedScan": true,
    "runnerLimit": 10,
    "concurrentJobLimit": 10
  },
  "runners": [
    {
      "id": "runner-1",
      "name": "prod-runner-1",
      "status": "online",
      "configuredConcurrency": 1,
      "currentJobs": 0
    }
  ]
}

POST/v1/runners/enrollment-tokens

Create runner enrollment token

Creates a one-time token used by `apviso register --token ...` or `apviso onboard` in `~/Documents/apviso-runner`. The token can be exchanged once for a runner-scoped token (`apvr_...`).

Enrollment tokens are short-lived and single-use. The runner daemon should run with `APVISO_RUNNER_TOKEN`, not the user API key.

Request Body

Name	Type	Description
`name`	`string`	Suggested runner name shown during registration.

Example Request

bash

curl -X POST "https://apviso.com/api/v1/runners/enrollment-tokens" \
  -H "X-API-Key: apvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "prod-runner-1"
}'

Response

Returns the raw enrollment token once. Store it briefly and pass it to the runner registration command.

json

{
  "token": "apve_a1b2c3d4e5f6_redacted",
  "tokenPrefix": "a1b2c3d4e5f6",
  "expiresAt": "2026-05-03T09:45:32Z"
}

Back to API Reference