{
  "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, and change its routing.",
    "description": "The 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. The routes that change settings work only in workspaces where the person turned on Allow changes for the connection in Settings › Agents. 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.dev/docs/reference/api"
  },
  "servers": [
    {
      "url": "https://api.relayrunner.dev/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. `version` changes whenever the order does.",
        "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": "object"
                    },
                    "isDefault": {
                      "type": "boolean"
                    },
                    "version": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "order",
                    "isDefault",
                    "version"
                  ]
                }
              }
            }
          },
          "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"
          }
        }
      },
      "put": {
        "operationId": "setRunnerOrder",
        "summary": "Set the runner order",
        "description": "Replaces the runner order. With `version`, it fails with 409 RUNNER_ORDER_CHANGED if the order changed since that version was read. Needs Allow changes for the agent in the workspace (Settings › Agents); otherwise 403 AGENT_CHANGES_OFF. Logged in Activity.",
        "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"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "steps": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "version": {
                    "type": "string"
                  }
                },
                "required": [
                  "steps"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The new order and the one it replaced.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "order": {
                      "type": "object"
                    },
                    "version": {
                      "type": "string"
                    },
                    "previous": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "order",
                    "version",
                    "previous"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/workspaces/{workspaceId}/auto-jobs": {
      "get": {
        "operationId": "listAutoJobs",
        "summary": "List auto jobs",
        "description": "Jobs whose relay lets RelayRunner pick the runner, from the last 30 days, with each one's size and first provider (null is the default) and whether you may change it (`canEdit`), and the default size.",
        "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 default size and the auto jobs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "size": {
                      "type": "integer"
                    },
                    "jobs": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "size",
                    "jobs"
                  ]
                }
              }
            }
          },
          "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}/auto-jobs/{jobId}": {
      "put": {
        "operationId": "setJobSize",
        "summary": "Set a job's size",
        "description": "One auto job's size in vCPUs and the provider it tries first. Null puts either back on the default; one left out stays as it is. Owners and admins can change any job, and anyone who can push to the job's repo on GitHub can change its jobs. Needs Allow changes for the agent in the workspace (Settings › Agents); otherwise 403 AGENT_CHANGES_OFF. Logged in Activity.",
        "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"
            }
          },
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "size": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "enum": [
                      2,
                      4,
                      8,
                      16,
                      32,
                      null
                    ]
                  },
                  "first": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "enum": [
                      "machine",
                      "github",
                      "blacksmith",
                      "depot",
                      "namespace",
                      "warpbuild",
                      "ubicloud",
                      "boat",
                      "runs-on",
                      "starsling",
                      "monkci",
                      "runloft",
                      "latchkey",
                      "berrybox",
                      "celesto",
                      "instabox",
                      "lizard",
                      null
                    ]
                  }
                },
                "required": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The new setting and the one it replaced.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "previous": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "previous"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/workspaces/{workspaceId}/auto-size": {
      "put": {
        "operationId": "setDefaultSize",
        "summary": "Set the default size",
        "description": "The size, in vCPUs, of auto jobs without their own. Needs Allow changes for the agent in the workspace (Settings › Agents); otherwise 403 AGENT_CHANGES_OFF. Logged in Activity.",
        "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"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "size": {
                    "type": "integer",
                    "enum": [
                      2,
                      4,
                      8,
                      16,
                      32
                    ]
                  }
                },
                "required": [
                  "size"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The new size and the one it replaced.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "size": {
                      "type": "integer"
                    },
                    "previous": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "size",
                    "previous"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/workspaces/{workspaceId}/retry-settings": {
      "get": {
        "operationId": "getRetrySettings",
        "summary": "Get automatic retries",
        "description": "Whether jobs a runner failed are re-run, where, and how many times per run.",
        "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 retry settings.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "runner": {
                      "type": "string"
                    },
                    "max": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "enabled",
                    "runner",
                    "max"
                  ]
                }
              }
            }
          },
          "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"
          }
        }
      },
      "put": {
        "operationId": "setRetrySettings",
        "summary": "Set automatic retries",
        "description": "Turns automatic retries on or off. A setting left out stays as it is. Needs Allow changes for the agent in the workspace (Settings › Agents); otherwise 403 AGENT_CHANGES_OFF. Logged in Activity.",
        "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"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "runner": {
                    "type": "string",
                    "enum": [
                      "any",
                      "same",
                      "other"
                    ]
                  },
                  "max": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 2
                  }
                },
                "required": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The new settings and the ones they replaced.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "previous": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "previous"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/workspaces/{workspaceId}/ai": {
      "get": {
        "operationId": "getAi",
        "summary": "Get AI",
        "description": "When the workspace turned off AI features, or null while they're 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": "Whether AI is off.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "offAt": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "offAt"
                  ]
                }
              }
            }
          },
          "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"
          }
        }
      },
      "put": {
        "operationId": "setAi",
        "summary": "Turn AI on or off",
        "description": "Turning AI off also deletes the AI answers saved so far. Needs Allow changes for the agent in the workspace (Settings › Agents); otherwise 403 AGENT_CHANGES_OFF. Logged in Activity.",
        "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"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "enabled"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Whether AI is on now, and before.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "previous": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "enabled",
                    "previous"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$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"
          }
        }
      }
    },
    "/machines/{machineId}/pause": {
      "post": {
        "operationId": "pauseRunner",
        "summary": "Pause a runner",
        "description": "Stops routing jobs to a runner, in every workspace, until it's resumed. Only a connected machine's owner, or an owner or admin for a runner added from GitHub. Needs Allow changes for the agent in the workspace (Settings › Agents); otherwise 403 AGENT_CHANGES_OFF. Logged in Activity.",
        "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": "machineId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The runner.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "machine": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "machine"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/machines/{machineId}/resume": {
      "post": {
        "operationId": "resumeRunner",
        "summary": "Resume a runner",
        "description": "Routes jobs to a paused runner again. Same rules as pausing. Needs Allow changes for the agent in the workspace (Settings › Agents); otherwise 403 AGENT_CHANGES_OFF. Logged in Activity.",
        "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": "machineId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The runner.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "machine": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "machine"
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$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",
                "settings"
              ]
            }
          },
          {
            "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.dev/.well-known/oauth-authorization-server/api/auth",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://app.relayrunner.dev/api/auth/oauth2/authorize",
            "tokenUrl": "https://app.relayrunner.dev/api/auth/oauth2/token",
            "refreshUrl": "https://app.relayrunner.dev/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.dev/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",
                        "AGENT_CHANGES_OFF",
                        "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",
                        "RUNNER_ORDER_CHANGED",
                        "PROVIDER_UNKNOWN",
                        "PROVIDER_INVALID",
                        "PROVIDER_ID_INVALID",
                        "PROVIDER_PREFIXES_INVALID",
                        "PROVIDER_EXISTS",
                        "PROVIDER_PREFIX_TAKEN",
                        "PROVIDER_NOT_CONNECTED",
                        "PROVIDER_ORGANIZATION_MISMATCH",
                        "PROVIDER_WORKSPACE_UNCLEAR",
                        "PROVIDER_TOKEN_REJECTED",
                        "PROVIDER_UNREACHABLE",
                        "PRICE_INVALID",
                        "PRICE_EXISTS",
                        "TOKEN_STORAGE_UNAVAILABLE",
                        "TELEMETRY_ENDPOINT_INVALID",
                        "TELEMETRY_HEADER_MISSING",
                        "TELEMETRY_NOT_CONFIGURED",
                        "BUCKET_INVALID",
                        "BUCKET_SECRET_MISSING",
                        "BUCKET_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."
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
