Runners

Endpoints for registering, monitoring, and interacting with external AI review runners.

Runners are external agents that execute AI reviews in isolated environments (containers). They communicate with the server over HTTP using an API key for authentication.

All runner endpoints are under /api/runners. Management endpoints (list, get) require a user session or API key. Task endpoints (register, heartbeat, task pickup, result submission) require an API key passed as Authorization: Bearer <key> or x-api-key: <key>.

---

List runners

GET /api/runners

Returns all registered runners ordered by most recent heartbeat. Requires authentication.

curl -X GET https://your-domain.com/api/runners \
  -H "Authorization: Bearer <api-key>"

Response 200

data · array

Show Runner fields

id · string

Runner UUID (set by the runner on registration).

name · string

Runner display name.

version · string

Runner software version.

status · string

online | busy | offline

currentJobs · number

Number of jobs currently running.

maxConcurrentJobs · number

Maximum concurrent jobs this runner accepts.

totalJobsCompleted · number

Lifetime completed job count.

totalJobsFailed · number

Lifetime failed job count.

tags · array

String tags used for runner selection.

lastHeartbeat · string | null

ISO 8601 timestamp of last heartbeat.

registeredAt · string

ISO 8601 registration timestamp.

---

Get a runner

GET /api/runners/:id

Returns details for a specific runner. Requires authentication.

id · string · required

Runner UUID.

Response 200

data · object

Single runner record. Same fields as the list response.

---

Register a runner

POST /api/runners/register

Registered or re-registers a runner. Runners call this endpoint on startup. Uses an upsert — if the runner ID already exists, its fields are updated.

This endpoint requires an API key. Registration metadata is passed via custom headers rather than a JSON body.

curl -X POST https://your-domain.com/api/runners/register \
  -H "x-api-key: <api-key>" \
  -H "x-runner-id: runner-001" \
  -H "x-runner-name: My Runner" \
  -H "x-runner-version: 1.2.0" \
  -H "x-runner-max-concurrency: 3" \
  -H "x-runner-tags: gpu,fast"

Request headers

x-runner-id · string · required

Unique identifier for this runner instance.

x-runner-name · string

Human-readable name. Defaults to the runner ID.

x-runner-version · string

Runner software version string. Defaults to unknown.

x-runner-max-concurrency · number

Maximum number of concurrent review jobs. Default: 5.

x-runner-tags · string

Comma-separated list of tags (e.g., gpu,fast).

Response 200

data · object

The created or updated runner record.

---

Runner heartbeat

POST /api/runners/:id/heartbeat

Runners send this periodically to report their current status. Requires API key authentication.

id · string · required

Runner UUID.

Request body

status · string · required

Current runner state: online | busy | offline.

currentJobs · number · required

Number of jobs currently being processed.

---

Claim pending tasks

GET /api/runners/tasks/pending

Returns pending review tasks for a runner to claim and execute. Requires API key authentication.

runnerId · string · required

ID of the runner requesting tasks.

limit · string

Maximum number of tasks to claim. Default: 1.

Response 200

data · array

List of claimed runner task objects, each containing repository URL, branch, commit SHA, file changes, and AI configuration.

---

Update task status

POST /api/runners/tasks/:id/status

Updates the execution phase of a task while it is running. Requires API key authentication.

id · string · required

Runner task UUID.

Request body

status · string · required

Current phase: preparing | cloning | reviewing | submitting.

---

Append task logs

POST /api/runners/tasks/:id/logs

Appends log lines to a running task. Requires API key authentication.

id · string · required

Runner task UUID.

Request body

logs · array · required

Array of log line strings. Between 1 and 200 entries per call.

---

Submit task result

POST /api/runners/tasks/:id/result

Submits the final result of a completed review task. Requires API key authentication. This triggers comment posting and review record updates.

id · string · required

Runner task UUID.

Request body

runnerId · string · required

ID of the runner submitting the result.

status · string · required

Final task outcome: success | failed.

files · array · required

Per-file review results.

Show File result fields

filePath · string · required

File path.

status · string · required

success | failed

comments · array · required

Array of comment objects with line, severity (info | warning | error), and message.

summary · string

AI-generated file summary.

error · string

Error message if the file review failed.

totalComments · number · required

Total number of comments across all files.

rating · string

Overall quality rating: A | B | C | D | F.

metrics · object · required

Timing metrics for the review execution.

Show Metrics fields

durationMs · number · required

Total wall-clock time in milliseconds.

containerPrepareMs · number · required

Time spent preparing the container.

cloneMs · number · required

Time spent cloning the repository.

reviewMs · number · required

Time spent running AI review.

submitMs · number · required

Time spent submitting results.

tokensUsed · number

Total tokens consumed across all AI calls.

error · string

Top-level error message if the task failed.

logs · array

Final batch of log lines to append.

---

Deregister a runner

DELETE /api/runners/:id

Marks a runner as offline. Can be called by the runner itself (API key) or by an authenticated user.

id · string · required

Runner UUID to deregister.