Runners
Build runner management — register, heartbeat, job claim/status.
Authorization
bearer_auth In: header
Query Parameters
Search runners
Sort field
Sort direction
Page size
int64Page offset
int64Response Body
application/json
curl -X GET "https://example.com/v1/runners"{ "online_total": 0, "runners": [ { "capabilities": {}, "created_at": 0, "id": "string", "last_heartbeat_at": 0, "name": "string", "registered_by": "string", "status": "online", "updated_at": 0 } ], "total": 0}Registers a new build runner and returns a runner authentication token.
Authorization
bearer_auth In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://example.com/v1/runners/register" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{ "runner": { "capabilities": {}, "created_at": 0, "id": "string", "last_heartbeat_at": 0, "name": "string", "registered_by": "string", "status": "online", "updated_at": 0 }, "token": "string"}Retrieves a single runner by ID, including its current status and health information.
Authorization
bearer_auth In: header
Path Parameters
Runner ID
Response Body
application/json
application/json
curl -X GET "https://example.com/v1/runners/string"{ "runner": { "capabilities": {}, "created_at": 0, "id": "string", "last_heartbeat_at": 0, "name": "string", "registered_by": "string", "status": "online", "updated_at": 0 }}Authorization
bearer_auth In: header
Path Parameters
Runner ID
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X PATCH "https://example.com/v1/runners/string" \ -H "Content-Type: application/json" \ -d '{}'{ "runner": { "capabilities": {}, "created_at": 0, "id": "string", "last_heartbeat_at": 0, "name": "string", "registered_by": "string", "status": "online", "updated_at": 0 }}Deletes a user-registered runner that has never claimed a build.
Authorization
bearer_auth In: header
Path Parameters
Runner ID
Response Body
application/json
application/json
application/json
curl -X DELETE "https://example.com/v1/runners/string"Runner claims the next queued build. Returns null job if no builds are available.
Authorization
bearer_auth In: header
Path Parameters
Runner ID
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://example.com/v1/runners/string/claim" \ -H "Content-Type: application/json" \ -d '{ "protocol_version": 0 }'{ "job": null}Sends a heartbeat from a runner to report its status. Authenticated via runner token.
Authorization
bearer_auth In: header
Path Parameters
Runner ID
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
curl -X POST "https://example.com/v1/runners/string/heartbeat" \ -H "Content-Type: application/json" \ -d '{ "status": "string" }'Runner checks the current status of its assigned build.
Authorization
bearer_auth In: header
Path Parameters
Runner ID
Build/Job ID
Response Body
application/json
curl -X GET "https://example.com/v1/runners/string/jobs/string"{ "status": "string"}Internal Git smart-HTTP endpoint. The runner token is accepted only for the repository assigned to this job; GitLab credentials remain server-side.
Authorization
bearer_auth In: header
Path Parameters
Runner ID
Build/Job ID
Multi-segment assigned repository info/refs path; preserve slash separators
Query Parameters
Must be git-upload-pack
Response Body
application/x-git-upload-pack-advertisement
application/json
curl -X GET "https://example.com/v1/runners/string/jobs/string/gitlab/string?service=string""string"Authorization
bearer_auth In: header
Path Parameters
Runner ID
Build/Job ID
Multi-segment assigned repository git-upload-pack path; preserve slash separators
Request Body
application/x-git-upload-pack-request
Git upload-pack request
TypeScript Definitions
Use the request body type in TypeScript.
binaryResponse Body
application/x-git-upload-pack-result
application/json
curl -X POST "https://example.com/v1/runners/string/jobs/string/gitlab/string" \ -H "Content-Type: application/x-git-upload-pack-request" \ -d 'string'"string"Runner reports build status transitions and step results.
Authorization
bearer_auth In: header
Path Parameters
Runner ID
Build/Job ID
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
curl -X POST "https://example.com/v1/runners/string/jobs/string/status" \ -H "Content-Type: application/json" \ -d '{ "status": "string" }'{ "build": { "branch": "string", "build_number": 0, "changelog": "string", "commit_sha": "string", "config_snapshot": {}, "context": null, "created_at": 0, "exit_code": 0, "finished_at": 0, "id": "string", "pipeline_id": "string", "project_id": "string", "queued_at": 0, "runner_id": "string", "runner_policy_block_reason": null, "source_build_id": "string", "started_at": 0, "status": "queued", "step_results": [ { "duration_ms": 0, "exit_code": 0, "finished_at": 0, "name": "string", "started_at": 0, "status": "string" } ], "trigger_actor": "string", "trigger_event": "string", "trigger_ref": "string", "trigger_type": "manual", "updated_at": 0 }, "events": [ { "actor": "string", "build_id": "string", "created_at": 0, "from_status": "string", "id": "string", "reason": "string", "to_status": "string" } ]}Settings
Instance-wide configuration — artifact storage, key storage preferences. Build retention and cleanup — automatic cleanup of old builds and artifacts based on age, count, or size policies. Outbound notification channel configuration — webhook, Mattermost. Daemon runtime and metrics.
Health check GET
Returns daemon build metadata when the daemon is running.