Skip to content
OpenRelay is in early access, and the /v1 API is stable. New capabilities ship in the changelog.
PricingDashboard
GuidesAPI ReferenceCLI
API ReferenceComputeRunners

Create a runner pool

Connects a GitHub organization's App installation as a runner pool and starts its subscription. Repeating it returns the pool while it is active or suspended. name defaults to the GitHub owner, poolRamGb to 64 when omitted or 0, and diskSizeGb to 100 when omitted. A payment method must be on file (CARD_REQUIRED), and a personal GitHub account is refused (USER_ACCOUNT_UNSUPPORTED). When the OAuth flow is configured, pass the installation's grant from listRunnerInstallations (GRANT_REQUIRED).

Required permission

Requires the runner.write permission. See Permissions for the roles and API key permissions that include it.

Command line

The orl CLI wraps this endpoint:

orl runners pool create --installation-id <installation-id>
POST
/v1/orgs/{orgId}/runner-pools

Authorization

apiKey
headerAuthorizationBearer <token>

OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).

Path Parameters

orgId*string

Request Body

application/json
  1. body
name?string
installationId*integer
Formatint64
githubOwner?string
githubOwnerType?string
poolRamGb?integer
diskSizeGb?integer
grant?string

The connectGrant of the chosen installation from listRunnerInstallations. Required when the OAuth flow is configured (getRunnerConnectUrl answers oauth: true).

Response Body

Created

application/json
  1. response
id*string
organizationId*string
name*string
githubInstallationId*integer
Formatint64
githubOwner*string
githubOwnerType*string
poolRamGb*integer
diskSizeGb*integer
runtime?string
status*string
subscriptionStatus?string
trialEndsAt?string
currentPeriodEnd?string
createdAt*string
updatedAt*string
Example Request
curl -X POST 'https://api.openrelay.inc/v1/orgs/string/runner-pools' \  -H 'Content-Type: application/json' \  -d '{  "installationId": 0}'
Example Response
{  "id": "string",  "organizationId": "string",  "name": "string",  "githubInstallationId": 0,  "githubOwner": "string",  "githubOwnerType": "string",  "poolRamGb": 0,  "diskSizeGb": 0,  "runtime": "string",  "status": "string",  "subscriptionStatus": "string",  "trialEndsAt": "string",  "currentPeriodEnd": "string",  "createdAt": "string",  "updatedAt": "string"}

List runner pools (with active/queued usage) GET

Returns the organization's GitHub runner pools, newest first, with active and queued runner counts and the RAM they hold. Deleted pools are left out.

Get the GitHub connect URL GET

Returns the URL that starts a GitHub connection: the OAuth authorize URL when OAuth is configured, otherwise the GitHub App install URL. installUrl carries the App install URL (empty when no App is configured), for installing the App on another GitHub organization.