Skip to main content
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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us