canonical: https://jentic.com/apis/cloudbees.com/cloudbees-ci-api

# CloudBees CI REST API

Jentic publishes the only available OpenAPI specification for CloudBees CI REST API, keeping it validated and agent-ready. CloudBees CI (formerly CloudBees Jenkins Enterprise) is the enterprise distribution of Jenkins and exposes a REST API compatible with Jenkins core. The endpoints cover instance and job introspection, build triggering with or without parameters, build cancellation, console log retrieval, build queue and node visibility, and CRUD operations on a job's config.xml. Authentication uses HTTP basic with the CloudBees CI username and an API token generated from the user profile page.

## For AI agents

Trigger Jenkins-style jobs, monitor builds and queues, retrieve console output, and manage job configurations on a CloudBees CI controller.

## Scope

Does not handle source-control hosting, artifact storage, or non-Jenkins CI platforms - use for triggering and monitoring builds on a CloudBees CI controller only.

## Capabilities

- Trigger a job with POST `/job/{jobName}/build` or with parameters via /buildWithParameters
- Read live build status, parameters, and result for a specific build number
- Cancel an in-flight build with the /stop endpoint
- Retrieve raw console output for a build via /consoleText for log-driven analysis
- Inspect the build queue and registered nodes (computers) on the controller
- Create new jobs by posting a config.xml payload to /createItem
- Read or replace a job's config.xml to manage pipeline definitions as code

## Use cases

### Webhook-Driven Builds

Trigger CloudBees CI builds from external systems - Slack commands, custom git hosts, or workflow tools - by calling `/job/{jobName}/build` or `/job/{jobName}/buildWithParameters.` The endpoints accept parameters used by the Jenkinsfile and queue the build immediately. This replaces brittle Jenkins-side webhook plugins with a clean external HTTP call.

Example prompt: POST to `/job/deploy/buildWithParameters` with branch=main and environment=staging, then poll the queue for the assigned build number

### Build Monitoring Dashboards

Aggregate build state across many CloudBees CI controllers into a single dashboard. `/api/json` on the controller returns the job list, `/job/{jobName}/api/json` returns the latest build per job, and `/job/{jobName}/{buildNumber}/api/json` returns per-build detail. The combination supports a dependable build status panel without parsing the Jenkins UI.

Example prompt: Fetch `/api/json` then iterate jobs and call `/job/{jobName}/api/json` for each, reporting jobs whose latest build failed

### Failure Triage Automations

On a failed build, automatically retrieve the console output via `/job/{jobName}/{buildNumber}/consoleText` and feed the tail into a triage tool or LLM that classifies the failure (test failure vs infra timeout vs flake). The /stop endpoint can cancel a stuck build before retry, keeping queue capacity healthy on busy controllers.

Example prompt: On build failure event, GET `/job/{jobName}/{buildNumber}/consoleText` and post the last 500 lines to the triage channel

### Pipeline-as-Code Management

Manage Jenkins job definitions as code by reading and writing config.xml from a Git repository. GET `/job/{jobName}/config.xml` exports the current definition, POST replaces it, and POST /createItem creates a new job from a config.xml template. This is the canonical pattern for keeping Jenkins configs reviewable in pull requests.

Example prompt: Read the current `/job/release/config.xml`, apply a diff to update the cron schedule, then POST it back

### Agent-Driven CI Operations via Jentic

AI assistants for platform engineers can answer 'rerun the deploy job for last night's failed run' by searching Jentic for an intent and executing the matching trigger or stop operation. The CloudBees CI API token sits in your Jentic One instance and is injected as basic auth per call, which keeps long-lived tokens out of the agent's context across many controllers.

Example prompt: Search Jentic for 'trigger cloudbees ci build', load `/job/{jobName}/build`, and execute it for the named job

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/json` | Controller-level API root |
| POST | `/job/{jobName}/build` | Trigger a build |
| POST | `/job/{jobName}/buildWithParameters` | Trigger a build with parameters |
| GET | `/job/{jobName}/{buildNumber}/api/json` | Get build details |
| POST | `/job/{jobName}/{buildNumber}/stop` | Cancel a build |
| GET | `/job/{jobName}/{buildNumber}/consoleText` | Get build console log |
| GET | `/queue/api/json` | Read the build queue |
| POST | `/createItem` | Create a new job from config.xml |

## Key resources

- **jobs** — Job listing and per-job introspection
- **builds** — Per-build status, parameters, and console output
- **queue** — Pending build queue on the controller
- **computer** — Connected agents (nodes) on the controller
- **config** — Job config.xml read/write for pipeline-as-code

## Why Jentic

- **Setup:** Wiring the CloudBees CI REST API by hand means setting up basic auth with a username and API token, targeting your own {instance_url} controller, and handling the Jenkins-style crumb and URL conventions yourself. Through Jentic you install once, import the CloudBees CI REST API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** CloudBees CI puts the job name in the URL path (`/job/{jobName}/...`), so a rule can pin your agent to one job: it can trigger builds and read console output for that job and nothing else. You choose the operations it may call, so stopping a build or creating an item is only in reach if you include it.
- **Credential handling:** Your CloudBees CI username and API token are stored once, encrypted, by your own Jentic One instance and injected as the basic-auth credential at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'trigger a CloudBees CI build' or 'get a build console log', and Jentic returns the matching operation with its parameter schema so the agent calls the right endpoint without reading Jenkins URL conventions.

## Related APIs

- **CircleCI** — Hosted CI/CD platform with config-as-code and orbs.
- **Buildkite** — Hybrid CI with hosted control plane and self-hosted build agents.
- **GitHub** — Source-of-truth for code that drives CloudBees CI builds.
- **CloudBees Codeship** — CloudBees' SaaS CI offering, complementary for teams running parallel SaaS pipelines.

## FAQ

### Why is there no official OpenAPI spec for CloudBees CI REST API?

CloudBees does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call CloudBees CI REST API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the CloudBees CI REST API use?

The API uses HTTP basic authentication with the user's CloudBees CI username and an API token generated from {instance_url}/me/configure. Through Jentic, the username and token are stored encrypted in the vault and injected per call so the raw token never enters the agent's context.

### Can I trigger a parameterised build with this API?

Yes. POST `/job/{jobName}/buildWithParameters` accepts the parameters expected by the Jenkinsfile as form data and queues the build immediately. The build's queued ID is returned in the Location header so the caller can poll the queue for the assigned build number.

### What are the rate limits for the CloudBees CI REST API?

CloudBees CI itself does not impose a documented rate limit - limits depend on the controller's resources and the plugin set. Treat the API as low-volume control-plane traffic and avoid bursting more than a few requests per second per controller, especially for /consoleText.

### How do I retrieve a build's console output through Jentic?

Run pip install jentic, search for 'get cloudbees ci console log', load the GET `/job/{jobName}/{buildNumber}/consoleText` operation, then execute with the job name and build number. The call returns the raw console text.

### Does this API let me create new jobs from a config.xml file?

Yes. POST /createItem with a name query parameter and an XML body creates a new job. Existing jobs can be updated by POSTing the new XML to `/job/{jobName}/config.xml`, which is the canonical Jenkins pattern for pipeline-as-code workflows.

### Can I limit what my agent is allowed to do with the CloudBees CI REST API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use. Since CloudBees CI puts the job name in the URL path (`/job/{jobName}/...`), a rule can pin the agent to a single job so it can only trigger builds and read console output for that job and nothing else. You also choose the exact operations it may call, so stopping a build with /stop or creating a job with /createItem is only in reach if you explicitly include it.