Oore CI

Runners

Build runner management — register, heartbeat, job claim/status.

List runners

GET
/v1/runners

Authorization

bearer_auth
AuthorizationBearer <token>

In: header

Query Parameters

q?string

Search runners

sort?string

Sort field

direction?string

Sort direction

limit?integer

Page size

Formatint64
offset?integer

Page offset

Formatint64

Response Body

application/json

curl -X GET "https://example.com/v1/runners"
{  "online_total": 0,  "queued_total": 0,  "runners": [    {      "cache_purge_requested_at": 0,      "capabilities": {},      "created_at": 0,      "custom_labels": [        "string"      ],      "disk_pressure": null,      "id": "string",      "labels": [        "string"      ],      "last_heartbeat_at": 0,      "max_concurrent_builds": 0,      "metrics": null,      "name": "string",      "registered_by": "string",      "status": "online",      "updated_at": 0    }  ],  "total": 0,  "unmatched_queued_total": 0}

Register runner

POST
/v1/runners/register

Registers a new build runner and returns a runner authentication token.

Authorization

bearer_auth
AuthorizationBearer <token>

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": {    "cache_purge_requested_at": 0,    "capabilities": {},    "created_at": 0,    "custom_labels": [      "string"    ],    "disk_pressure": null,    "id": "string",    "labels": [      "string"    ],    "last_heartbeat_at": 0,    "max_concurrent_builds": 0,    "metrics": null,    "name": "string",    "registered_by": "string",    "status": "online",    "updated_at": 0  },  "token": "string"}

Get runner

GET
/v1/runners/{runner_id}

Retrieves a single runner by ID, including its current status and health information.

Authorization

bearer_auth
AuthorizationBearer <token>

In: header

Path Parameters

runner_id*string

Runner ID

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/runners/string"
{  "runner": {    "cache_purge_requested_at": 0,    "capabilities": {},    "created_at": 0,    "custom_labels": [      "string"    ],    "disk_pressure": null,    "id": "string",    "labels": [      "string"    ],    "last_heartbeat_at": 0,    "max_concurrent_builds": 0,    "metrics": null,    "name": "string",    "registered_by": "string",    "status": "online",    "updated_at": 0  }}

Update runner

PATCH
/v1/runners/{runner_id}

Authorization

bearer_auth
AuthorizationBearer <token>

In: header

Path Parameters

runner_id*string

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": {    "cache_purge_requested_at": 0,    "capabilities": {},    "created_at": 0,    "custom_labels": [      "string"    ],    "disk_pressure": null,    "id": "string",    "labels": [      "string"    ],    "last_heartbeat_at": 0,    "max_concurrent_builds": 0,    "metrics": null,    "name": "string",    "registered_by": "string",    "status": "online",    "updated_at": 0  }}

Delete runner

DELETE
/v1/runners/{runner_id}

Deletes a user-registered runner that has never claimed a build.

Authorization

bearer_auth
AuthorizationBearer <token>

In: header

Path Parameters

runner_id*string

Runner ID

Response Body

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/runners/string"
Empty

Purge runner caches

POST
/v1/runners/{runner_id}/caches/purge

Asks a runner to delete its dependency caches (pub, Gradle, CocoaPods and Xcode DerivedData). The runner purges before its next build and clears cache_purge_requested_at through its heartbeat.

Authorization

bearer_auth
AuthorizationBearer <token>

In: header

Path Parameters

runner_id*string

Runner ID

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/v1/runners/string/caches/purge"
{  "runner": {    "cache_purge_requested_at": 0,    "capabilities": {},    "created_at": 0,    "custom_labels": [      "string"    ],    "disk_pressure": null,    "id": "string",    "labels": [      "string"    ],    "last_heartbeat_at": 0,    "max_concurrent_builds": 0,    "metrics": null,    "name": "string",    "registered_by": "string",    "status": "online",    "updated_at": 0  }}

Claim job

POST
/v1/runners/{runner_id}/claim

Runner claims the next queued build. Returns null job if no builds are available.

Authorization

bearer_auth
AuthorizationBearer <token>

In: header

Path Parameters

runner_id*string

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}

Runner heartbeat

POST
/v1/runners/{runner_id}/heartbeat

Sends a heartbeat from a runner to report its status. Authenticated via runner token. capabilities.caches carries dependency cache sizes; the response carries a pending cache purge request.

Authorization

bearer_auth
AuthorizationBearer <token>

In: header

Path Parameters

runner_id*string

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/heartbeat" \  -H "Content-Type: application/json" \  -d '{    "status": "string"  }'
{  "cache_purge_requested_at": 0,  "max_concurrent_builds": 0}

Get job status

GET
/v1/runners/{runner_id}/jobs/{job_id}

Runner checks the current status of its assigned build.

Authorization

bearer_auth
AuthorizationBearer <token>

In: header

Path Parameters

runner_id*string

Runner ID

job_id*string

Build/Job ID

Response Body

application/json

curl -X GET "https://example.com/v1/runners/string/jobs/string"
{  "status": "string"}

Discover a private GitLab repository for checkout

GET
/v1/runners/{runner_id}/jobs/{job_id}/gitlab/{git_path}

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
AuthorizationBearer <token>

In: header

Path Parameters

runner_id*string

Runner ID

job_id*string

Build/Job ID

git_path*string

Multi-segment assigned repository info/refs path; preserve slash separators

Query Parameters

service*string

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"

Stream a private GitLab upload-pack request

POST
/v1/runners/{runner_id}/jobs/{job_id}/gitlab/{git_path}

Authorization

bearer_auth
AuthorizationBearer <token>

In: header

Path Parameters

runner_id*string

Runner ID

job_id*string

Build/Job ID

git_path*string

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.

body*BinaryPayload
Formatbinary

Response 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"

Get artifacts for a step retry

GET
/v1/runners/{runner_id}/jobs/{job_id}/retry-artifacts

Returns the source build's stored artifacts that a retry job uploads, with short-lived download URLs, while the job is active.

Authorization

bearer_auth
AuthorizationBearer <token>

In: header

Path Parameters

runner_id*string

Runner ID

job_id*string

Build/Job ID

Header Parameters

x-oore-signing-token*string

Job-scoped signing grant

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/runners/string/jobs/string/retry-artifacts" \  -H "x-oore-signing-token: string"
{  "artifacts": [    {      "artifact_type": "string",      "checksum": "string",      "download_url": "string",      "id": "string",      "metadata": {},      "name": "string"    }  ]}

Update job status

POST
/v1/runners/{runner_id}/jobs/{job_id}/status

Runner reports build status transitions and step results.

Authorization

bearer_auth
AuthorizationBearer <token>

In: header

Path Parameters

runner_id*string

Runner ID

job_id*string

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": {    "approval": null,    "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,    "retry_steps": [      "string"    ],    "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",        "publish_from_file": true,        "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"    }  ],  "retryable_steps": [    "string"  ]}