API introduction

The CloudBees cloud-native platform REST API allows you to interact with platform data using standard HTTP methods and JSON-formatted responses. With this API, you can:

POST data to create or update resources across the CloudBees platform.
GET data to retrieve information about configurations, environments, organizations, and more.
Build custom integrations to extend the platform’s functionality.
Create tailored workflows that align with your team’s needs.

For information on authentication and setup, refer to API setup and authentication.

Key features of the API

RESTful design: The API follows REST principles, making it intuitive and consistent to use.
JSON format: All requests and responses use JSON for compatibility with modern development tools.
Flexible integration: Whether you’re automating tasks or building custom apps, the API gives you the tools to manage resources and streamline workflows.

API audience

This API is designed for:

Developers: Build integrations and applications on top of the CloudBees platform. For implementation examples, refer to the SDK installation documentation.
System administrators: Automate environment and resource management programmatically.
Product teams: Access real-time platform data to support feature rollouts and decision-making.

API setup and authentication

This page provides details for authenticating with CloudBees platform using personal access tokens (PATs). It includes the base URL for all API calls, guidance on using the Authorization header, and setup steps for authenticating securely. Examples for use are also provided.

The following endpoint and headers are used to authenticate requests to CloudBees platform APIs:

Base URL

All API calls use the following base URL:

https://api.cloudbees.io/

Authorization header

To authenticate API requests, pass your personal access token in the Authorization header:

Authorization: Bearer <personal_access_token>

Tokens are linked to your user account and inherit all associated permissions.

Treat your personal access token like a password. Keep it secure and do not share it.

Examples

Use the examples below to authenticate your API calls with a personal access token (PAT). The first example shows how to include your PAT in the Authorization header; the second demonstrates generating a PAT via the UI, so you can quickly secure and automate your integrations with the CloudBees platform.

Example: Use a personal access token

Use the following format when making authenticated API requests with a personal access token.

Request

curl -L 'https://api.cloudbees.io/v1/example-endpoint' \
  --header 'Authorization: Bearer <personal_access_token>' \
  --header 'Content-Type: application/json'▼

Response

{
  "message": "Authenticated successfully"
}▼

Example: Generate a personal access token

Personal access tokens are typically created through the CloudBees platform UI under your user profile. Once created, you can use the token as shown in the example above.

If an endpoint to programmatically generate a token becomes available, it will be documented here.

References

To understand how APIs fit into the broader platform, refer to the CloudBees platform architecture.

As a quickstart, refer to the end-to-end example for creating an ephemeral environment.

Explore the API references and examples on the next page to get started!