{ "openapi": "3.1.0", "info": { "title": "RelayRunner API", "version": "1.0.0", "summary": "Read a workspace's runners, workflow runs, routing activity and CI usage.", "description": "The read-only API behind the RelayRunner MCP server: a workspace's runners, runs, routing and usage. Sign in with OAuth (the `workspace:read` scope): the person picks which workspaces the token may read. To connect an AI agent, use the MCP server at https://agents.relayrunner.app/mcp instead: MCP clients sign in on their own and get these routes as tools. Call this API directly only from your own OAuth client. Each connection can make 300 requests a minute; past that the API answers 429.", "contact": { "url": "https://github.com/relayrunner/relayrunner/issues" }, "license": { "name": "Apache-2.0", "identifier": "Apache-2.0" } }, "externalDocs": { "url": "https://relayrunner.app/docs/reference/api" }, "servers": [ { "url": "https://api.relayrunner.app/api" } ], "security": [ { "oauth": [ "workspace:read" ] } ], "paths": { "/me": { "get": { "operationId": "getMe", "summary": "Get the current user", "description": "The signed-in user and the workspaces this token may read.", "parameters": [ { "name": "x-relayrunner-workspace", "in": "header", "required": false, "description": "The workspace to read, by id. Needed only when the token's grant covers more than one workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The user and the token's grant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object" }, "agent": { "type": "object" } }, "required": [ "user", "agent" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/workspaces/current": { "get": { "operationId": "getWorkspace", "summary": "Get a workspace", "description": "One workspace, your role in it and its connected GitHub accounts.", "parameters": [ { "name": "x-relayrunner-workspace", "in": "header", "required": false, "description": "The workspace to read, by id. Needed only when the token's grant covers more than one workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "type": "object" }, "role": { "type": "string" }, "installations": { "type": "array", "items": { "type": "object" } } }, "required": [ "workspace", "role", "installations" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/workspaces/{workspaceId}/runner-order": { "get": { "operationId": "getRunnerOrder", "summary": "Get the runner order", "description": "The providers jobs are tried on, top to bottom.", "parameters": [ { "name": "x-relayrunner-workspace", "in": "header", "required": false, "description": "The workspace to read, by id. Needed only when the token's grant covers more than one workspace.", "schema": { "type": "string" } }, { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The runner order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "array", "items": { "type": "object" } }, "isDefault": { "type": "boolean" } }, "required": [ "order", "isDefault" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/workspaces/{workspaceId}/router-setup": { "get": { "operationId": "listWorkflows", "summary": "List workflows", "description": "Every workflow that ran in the workspace's repos in the last 14 days, with how many of its runs went through RelayRunner, unrouted first, plus the hosted provider labels jobs ran on.", "parameters": [ { "name": "x-relayrunner-workspace", "in": "header", "required": false, "description": "The workspace to read, by id. Needed only when the token's grant covers more than one workspace.", "schema": { "type": "string" } }, { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recent workflows and hosted labels.", "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer" }, "workflows": { "type": "array", "items": { "type": "object" } }, "labels": { "type": "array", "items": { "type": "object" } } }, "required": [ "days", "workflows", "labels" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/machines": { "get": { "operationId": "listRunners", "summary": "List runners", "description": "Every runner: connected machines and self-hosted runners from GitHub.", "parameters": [ { "name": "x-relayrunner-workspace", "in": "header", "required": false, "description": "The workspace to read, by id. Needed only when the token's grant covers more than one workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The workspace's runners.", "content": { "application/json": { "schema": { "type": "object", "properties": { "machines": { "type": "array", "items": { "type": "object" } } }, "required": [ "machines" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/runs": { "get": { "operationId": "listRuns", "summary": "List runs", "description": "Workflow runs from the last 14 days, newest first.", "parameters": [ { "name": "x-relayrunner-workspace", "in": "header", "required": false, "description": "The workspace to read, by id. Needed only when the token's grant covers more than one workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recent runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object" } }, "truncated": { "type": "boolean" } }, "required": [ "runs", "truncated" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/runs/{repositoryId}/{runId}/{runAttempt}/jobs": { "get": { "operationId": "getRunJobs", "summary": "List a run's jobs", "description": "One run attempt's jobs and where each ran.", "parameters": [ { "name": "x-relayrunner-workspace", "in": "header", "required": false, "description": "The workspace to read, by id. Needed only when the token's grant covers more than one workspace.", "schema": { "type": "string" } }, { "name": "repositoryId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "runAttempt", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "The run's jobs.", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/runs/{repositoryId}/{runId}/{runAttempt}/failures": { "get": { "operationId": "getRunFailures", "summary": "Explain a run's failures", "description": "Why a run attempt's jobs failed: each failed job's first failed step, whether its runner failed it before any step ran, GitHub's annotations, and the end of its log up to the last error. Covers up to 5 failed jobs.", "parameters": [ { "name": "x-relayrunner-workspace", "in": "header", "required": false, "description": "The workspace to read, by id. Needed only when the token's grant covers more than one workspace.", "schema": { "type": "string" } }, { "name": "repositoryId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "runAttempt", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "The run's failed jobs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object" } }, "more": { "type": "integer" } }, "required": [ "jobs", "more" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/activity": { "get": { "operationId": "listActivity", "summary": "List activity", "description": "The activity log, newest first: where each job was routed and why.", "parameters": [ { "name": "x-relayrunner-workspace", "in": "header", "required": false, "description": "The workspace to read, by id. Needed only when the token's grant covers more than one workspace.", "schema": { "type": "string" } }, { "name": "before", "in": "query", "description": "The previous page's nextBefore.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "filter", "in": "query", "schema": { "type": "string", "enum": [ "job", "check", "machine", "member" ] } }, { "name": "since", "in": "query", "description": "Only events after this time, in milliseconds since the epoch.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "repository", "in": "query", "description": "Only this repository (owner/name).", "schema": { "type": "string" } }, { "name": "result", "in": "query", "schema": { "type": "string", "enum": [ "passed", "failed", "cancelled", "skipped", "running" ] } }, { "name": "machine", "in": "query", "description": "Only this machine, by id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "One page of activity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "nextBefore": { "type": [ "integer", "null" ] } }, "required": [ "items", "nextBefore" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/usage": { "get": { "operationId": "getUsage", "summary": "Get usage", "description": "Jobs under a minute and what rounding up to whole minutes cost.", "parameters": [ { "name": "x-relayrunner-workspace", "in": "header", "required": false, "description": "The workspace to read, by id. Needed only when the token's grant covers more than one workspace.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "How many days back to look (1 to 90).", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } } ], "responses": { "200": { "description": "The usage report.", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/usage/checks": { "get": { "operationId": "getCheckSavings", "summary": "Get check savings", "description": "What optimized checks saved.", "parameters": [ { "name": "x-relayrunner-workspace", "in": "header", "required": false, "description": "The workspace to read, by id. Needed only when the token's grant covers more than one workspace.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "How many days back to look (1 to 90).", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } } ], "responses": { "200": { "description": "Optimized check savings.", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/usage/actions": { "get": { "operationId": "getActionsMinutes", "summary": "Get Actions minutes", "description": "Each connected GitHub account's Actions minutes this billing cycle.", "parameters": [ { "name": "x-relayrunner-workspace", "in": "header", "required": false, "description": "The workspace to read, by id. Needed only when the token's grant covers more than one workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Actions minutes by account.", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/job-times": { "get": { "operationId": "getJobTimes", "summary": "Get job times", "description": "How long each job usually takes on each runner environment.", "parameters": [ { "name": "x-relayrunner-workspace", "in": "header", "required": false, "description": "The workspace to read, by id. Needed only when the token's grant covers more than one workspace.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "How many days back to look (1 to 30).", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 14 } } ], "responses": { "200": { "description": "Job times by workflow, job and environment.", "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/signals": { "get": { "operationId": "getSignals", "summary": "Get signals", "description": "What's making CI slow, costly or busier than it needs to be: each signal's area, jobs, minutes, estimated cost and the repos and workflows it affects most, plus every job's minutes by person, repository, workflow, branch and trigger.", "parameters": [ { "name": "x-relayrunner-workspace", "in": "header", "required": false, "description": "The workspace to read, by id. Needed only when the token's grant covers more than one workspace.", "schema": { "type": "string" } }, { "name": "days", "in": "query", "required": false, "description": "How many days back to look (1 to 90).", "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } }, { "name": "breakdown", "in": "query", "description": "0 leaves out the breakdown.", "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 1 } } ], "responses": { "200": { "description": "Signals and the breakdown.", "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer" }, "totals": { "type": "object" }, "signals": { "type": "array", "items": { "type": "object" } } }, "required": [ "days", "totals", "signals" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/feedback": { "post": { "operationId": "sendFeedback", "summary": "Send feedback", "description": "Report a bug, a confusing result or a missing feature to the team.", "parameters": [ { "name": "x-relayrunner-workspace", "in": "header", "required": false, "description": "The workspace to read, by id. Needed only when the token's grant covers more than one workspace.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "category", "summary" ], "properties": { "category": { "type": "string", "enum": [ "bug", "confusing", "feature_request", "other" ] }, "summary": { "type": "string", "minLength": 1, "maxLength": 200 }, "details": { "type": "string", "maxLength": 4000 }, "tool": { "type": "string", "maxLength": 64 } } } } } }, "responses": { "201": { "description": "Stored. The answer never repeats what was sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "redacted": { "type": "integer" } }, "required": [ "id", "redacted" ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "oauth": { "type": "oauth2", "description": "OAuth 2.1 with PKCE. Clients can register themselves (dynamic client registration). Discovery: https://app.relayrunner.app/.well-known/oauth-authorization-server/api/auth", "flows": { "authorizationCode": { "authorizationUrl": "https://app.relayrunner.app/api/auth/oauth2/authorize", "tokenUrl": "https://app.relayrunner.app/api/auth/oauth2/token", "refreshUrl": "https://app.relayrunner.app/api/auth/oauth2/token", "scopes": { "workspace:read": "Read the workspaces the person picks." } } } } }, "responses": { "Error": { "description": "The request failed. Branch on `error.code`; `error.message` is for people and can change. See https://relayrunner.app/docs/reference/errors.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable. New codes can be added, so handle ones you don't know.", "enum": [ "INVALID_REQUEST", "PAYLOAD_TOO_LARGE", "NOT_FOUND", "METHOD_NOT_ALLOWED", "RATE_LIMITED", "INTERNAL_ERROR", "UNAUTHENTICATED", "INVALID_TOKEN", "FORBIDDEN", "AGENT_NOT_ALLOWED", "NOT_A_MEMBER", "LEGAL_TERMS_OUTDATED", "NO_ACTIVE_WORKSPACE", "WORKSPACE_REQUIRED", "CANNOT_DEMOTE_SELF", "CANNOT_DELETE_SELF", "USER_HAS_SHARED_WORKSPACES", "MACHINE_NOT_OWNED", "DEVICE_CODE_INVALID", "DEVICE_CODE_EXPIRED", "DEVICE_CODE_USED", "DEVICE_CODE_CLAIMED", "WEBSOCKET_REQUIRED", "RUNNER_ORDER_INVALID", "PROVIDER_UNKNOWN", "PROVIDER_INVALID", "PROVIDER_ID_INVALID", "PROVIDER_PREFIXES_INVALID", "PROVIDER_EXISTS", "PROVIDER_PREFIX_TAKEN", "PROVIDER_NOT_CONNECTED", "PROVIDER_TOKEN_REJECTED", "PROVIDER_UNREACHABLE", "PRICE_INVALID", "PRICE_EXISTS", "TOKEN_STORAGE_UNAVAILABLE", "TELEMETRY_ENDPOINT_INVALID", "TELEMETRY_HEADER_MISSING", "TELEMETRY_NOT_CONFIGURED", "WEBHOOK_SIGNATURE_INVALID", "WEBHOOK_SECRET_NOT_CONFIGURED", "WEBHOOK_ENQUEUE_FAILED", "GITHUB_UNAVAILABLE", "GITHUB_RATE_LIMITED", "GITHUB_APP_NOT_CONFIGURED" ] }, "message": { "type": "string" }, "details": { "description": "More context, on some codes." } } } } } } } } } } }