Skip to content

RelayRunner API

Read your workspace's runners, runs, routing and usage over HTTP, and change its routing.

The RelayRunner API is the HTTP API behind the MCP server. It reads a workspace’s runners, runs, routing and usage, and changes its routing where you allow it.

https://api.relayrunner.dev/api

API routes lists every route with its parameters and responses, and you can try them there. The OpenAPI spec has the same in JSON.

The API uses OAuth 2.1 with PKCE and the workspace:read scope. Clients can register themselves, and the authorization server publishes its endpoints at https://app.relayrunner.dev/.well-known/oauth-authorization-server/api/auth. While signing in, you pick which workspaces the token may read.

Send the access token as Authorization: Bearer <token>. Tokens last 15 minutes; use the refresh token for a new one. When a token covers more than one workspace, name the one you’re asking about in the x-relayrunner-workspace header.

Route What it returns
GET /me You and the workspaces the token may read
GET /workspaces/current One workspace, your role and its GitHub accounts
GET /workspaces/{id}/runner-order The providers jobs are tried on, in order
GET /workspaces/{id}/router-setup Recent workflows and how many of their runs were routed
GET /machines Runners, their status, labels, pause state and current job
GET /runs Workflow runs from the last 14 days
GET /runs/{repositoryId}/{runId}/{runAttempt}/jobs One run’s jobs and where each ran
GET /runs/{repositoryId}/{runId}/{runAttempt}/failures Why a run’s jobs failed, with the end of each log
GET /activity The activity log, including where each job was routed and why
GET /usage, /usage/checks, /usage/actions Short jobs and round-up cost, optimized check savings, Actions minutes
GET /job-times Typical job durations per runner
GET /signals What’s making CI slow, costly or busier than it needs to be
GET /workspaces/{id}/auto-jobs Auto jobs’ sizes and first providers, and the default size
GET /workspaces/{id}/retry-settings, /ai Automatic retries, and whether AI is on
POST /feedback Reports a bug, confusing result or missing feature to the team

These change settings. They work only in workspaces where the person turned on Allow changes for the connection under Settings → Agents, and only for changes the person could make in the dashboard: owners and admins for workspace settings, anyone who can push to a repo for its jobs’ sizes, and pausing by the dashboard’s rules. Elsewhere they answer 403 with AGENT_CHANGES_OFF or FORBIDDEN. Each change shows in the workspace’s Activity, and each answer includes the value it replaced as previous.

Route What it changes
PUT /workspaces/{id}/runner-order The runner order. Pass version from the GET to refuse a stale write
PUT /workspaces/{id}/auto-size The default size for auto jobs
PUT /workspaces/{id}/auto-jobs/{jobId} One auto job’s size and first provider
PUT /workspaces/{id}/retry-settings Automatic retries
PUT /workspaces/{id}/ai AI features, on or off
POST /machines/{id}/pause, /resume Whether jobs route to a runner

A failed request answers with a code and a message, such as {"error": {"code": "INVALID_REQUEST", "message": "The request isn't valid."}}. Errors lists every code.

Each person’s connection can make 300 requests a minute, counting requests from the MCP server too. Past that, the API answers 429 with the RATE_LIMITED code and a Retry-After header.