Create a runner
The response includes a plain_text_token -- the raw SAT secret shown
exactly once. Deploy this token to the runner binary for authentication.
Scope: runner:write
Authorization
bearerAuth Personal Access Token (PAT) or Service Access Token (SAT). Pass the token in the Authorization header: Bearer adm_pat_...
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://admiral.example.com/api/v1/runners" \ -H "Content-Type: application/json" \ -d '{}'{ "runner": { "id": "b2c3d4e5-6789-0abc-def1-234567890abc", "name": "prod-terraform-runner", "description": "Terraform runner for production AWS infrastructure provisioning.", "kind": "RUNNER_KIND_TERRAFORM", "labels": { "cloud": "aws", "team": "platform" }, "health_status": "RUNNER_HEALTH_STATUS_HEALTHY", "created_by": "d290f1ee-6c54-4b01-90e6-d701748f0851", "updated_by": "d290f1ee-6c54-4b01-90e6-d701748f0851", "created_at": "2025-07-15T10:00:00Z", "updated_at": "2025-11-18T08:30:00Z" }, "plain_text_token": "string"}Unlock state for a job POST
The server validates that the SAT's runner binding matches the runner assigned to this job. Returns PERMISSION_DENIED if they do not match. Returns FAILED_PRECONDITION if the lock_id does not match the currently held lock. Returns NOT_FOUND if no lock is held. Maps to Terraform HTTP backend POST on the unlock address. Scope: `state:write` | Token types: `sat`
Create a runner token POST
Use this to create additional SATs for an existing runner (e.g., for zero-downtime token rotation). The initial SAT is created automatically by CreateRunner. Scope: `runner:write`