Edge Runners API reference

The CloudBees Unify Edge Runners APIs allow you to manage edge runners. Use this reference when creating runner tokens, listing runners, retrieving runner details, or deleting runners within your CloudBees organizations.

Base URL: https://api.cloudbees.io/v1

Authentication: Bearer <your_api_token> (include your PAT token in the Authorization header).

For single tenant customers, the base URL format is https://api.<your_domain>.cloudbees.io/v1, where <your_domain> is your specific domain. For example, if your domain is example, the base URL is https://api.example.cloudbees.io/v1.

Create an Edge Runner token

Create a new edge runner token for a specific organization, that can be used to register edge runners. Runner tokens are organization-specific and cannot be used across different organizations.

Endpoint: POST /organizations/{organization_id}/edge/runner-token

Parameters:

organization_id (path parameter, required): The ID of the organization to create the edge runner token for.

Request Headers:

Authorization (required): Bearer token for authentication. Include your API token in the format Bearer <your_api_token>.

Response:

A successful response returns a 201 Created status code along with a JSON object containing the newly created edge runner token. If the user does not have the necessary permissions, an appropriate error response is returned.

Example Request:

curl -X POST \
  https://api.cloudbees.io/v1/organizations/{organization_id}/edge/runner-token \
  -H 'Authorization: Bearer <your_token>'▼

A generated token is valid for one hour and can be used to register multiple runners. After this period, the token will expire, and a new token must be created to register additional edge runners.

List Edge Runners

Retrieve a list of all edge runners associated with a specific organization. Requires Admin privileges. List operations support pagination to manage large sets of edge runners efficiently. The parents and children parameters allow you to include runners from parent and child organizations in the response, providing a comprehensive view of all runners associated with the organization hierarchy.

Endpoint: GET /organizations/{organization_id}/edge/runners

Parameters:

organization_id (path parameter, required): The ID of the organization to list edge runners for.
parents (query parameter, optional): Boolean flag to include runners from parent organizations (default is false).
children (query parameter, optional): Boolean flag to include runners from child organizations (default is false).

Request Headers:

Authorization (required): Bearer token for authentication. Include your API token in the format Bearer <your_api_token>.

Response:

A successful response returns a 200 OK status code along with a JSON array containing the list of edge runners associated with the specified organization. If the user does not have the necessary permissions, an appropriate error response is returned.

Example Request:

# List runners in current organization only
curl -X GET \
  https://api.cloudbees.io/v1/organizations/{organization_id}/edge/runners \
  -H 'Authorization: Bearer <your_token>'

# List runners including parent and child organizations
curl -X GET \
  'https://api.cloudbees.io/v1/organizations/{organization_id}/edge/runners?parents=true&children=true' \
  -H 'Authorization: Bearer <your_token>'▼

List Edge jobs

Retrieves a list of edge jobs associated with a specific organization. Requires Admin privileges. List operations support pagination to manage large sets of edge jobs efficiently. The parents and children parameters allow you to include jobs from parent and child organizations in the response, providing a comprehensive view of all jobs associated with the organization hierarchy.

Endpoint: GET /organizations/{organization_id}/edge/jobs

Parameters:

organization_id (path parameter, required): The ID of the organization to list edge jobs for.

Request Headers: * Authorization (required): Bearer token for authentication. Include your API token in the format Bearer <your_api_token>.

Response:

A successful response returns a 200 OK status code along with a JSON array containing the list of edge jobs associated with the specified organization. If the user does not have the necessary permissions, an appropriate error response is returned.

Example Request:

# List jobs in current organization only
curl -X GET \
  https://api.cloudbees.io/v1/organizations/{organization_id}/edge/jobs \
  -H 'Authorization: Bearer <your_token>'▼

Get Edge Runner details

Retrieve detailed information about a specific edge runner by its ID.

Endpoint: GET /organizations/{organization_id}/edge/runners/{runner_id}

Parameters:

organization_id (path parameter, required): The ID of the organization to which the edge runner belongs.
runner_id (path parameter, required): The ID of the edge runner to retrieve details for.

Request Headers:

Authorization (required): Bearer token for authentication. Include your API token in the format Bearer <your_api_token>.

Response:

A successful response returns a 200 OK status code along with a JSON object containing the details of the specified edge runner. If the specified edge runner does not exist or if the user does not have the necessary permissions, an appropriate error response is returned.

Example Request:

curl -X GET "https://api.cloudbees.io/v1/organizations/{organization_id}/edge/runners/{runner_id}" \
     -H "Authorization: Bearer <your_api_token>"▼

Unregister Edge Runners

Unregistered runners must be re-registered if needed.

As a best practice, CloudBees recommends stopping the runner process on the machine before unregistering it using the API. Ensure the runner’s assigned job has been completed before stopping.

For complete cleanup, delete the runner’s working directory on the machine after unregistering it. This removes any cached data or logs associated with the runner.

Endpoint: DELETE /organizations/{organization_id}/edge/runners/{runner_id}

Parameters:

organization_id (path parameter, required): The ID of the organization to which the edge runner belongs.
runner_id (path parameter, required): The ID of the edge runner to delete.

Request Headers:

Authorization (required): Bearer token for authentication. Include your API token in the format Bearer <your_api_token>.

Response:

A successful response returns a 204 No Content status code, indicating that the edge runner was successfully deleted. If the specified edge runner does not exist or if the user does not have the necessary permissions, an appropriate error response is returned.

Example Request:

curl -X DELETE "https://api.cloudbees.io/v1/organizations/{organization_id}/edge/runners/{runner_id}" \
     -H "Authorization: Bearer <your_api_token>"▼

Error codes

The following error codes may be returned by the CloudBees Unify Edge Runners APIs:

200 OK: The request was successful.
201 Created: The request was successful and a new resource was created (for example, when creating a runner token).
204 No Content: The request was successful but there is no content to return (for example, when deleting a runner).
400 Bad Request: The request was invalid or cannot be processed. This may occur if required parameters are missing or if the request body is malformed.
401 Unauthorized: Authentication failed. This may occur if the API token is missing, invalid, or expired.
403 Forbidden: The user does not have the necessary permissions to perform the requested action. This may occur if the user is not an admin or does not have the appropriate roles within the organization.
404 Not Found: The specified resource was not found. This may occur if the organization or edge runner ID does not exist.
500 Internal Server Error: An unexpected error occurred on the server. This may occur due to temporary issues or bugs in the API. If you encounter this error, try again later or contact CloudBees support for assistance.

Security and permissions

To access the CloudBees Unify Edge Runners APIs, you must have the appropriate permissions within your CloudBees organization.

For more information, refer to Understanding Edge Runners security, which provides guidelines on how to secure your edge runners and protect your workflows from potential threats.