canonical: https://jentic.com/apis/cloudbees.com

# CloudBees APIs

CloudBees offers two CI/CD platforms exposed through REST APIs in the Jentic directory: CloudBees CI, the enterprise distribution of Jenkins run on a self-hosted controller, and Codeship, a SaaS-hosted CI/CD service. Together they cover triggering and monitoring builds, retrieving console output and pipeline detail, managing job or project configuration, and rotating build secrets. Both specs are Jentic-generated and kept validated because CloudBees does not publish official OpenAPI documents.

## For AI agents

An agent can trigger and cancel builds, poll build status and queues, read console logs, and manage job or project configuration across a self-hosted CloudBees CI Jenkins controller and the Codeship SaaS platform. It can also inspect Codeship Pro pipelines, services, and steps and rotate a project's encryption key.

## Scope

Use for: Triggering, monitoring, and controlling CI/CD builds and job or project configuration on CloudBees CI controllers and the Codeship platform

Not supported:
- source-control hosting
- artifact storage
- deployment orchestration
- non-CloudBees CI platforms
- code scanning

## APIs

| API | Category | Endpoints | Description |
| --- | --- | --- | --- |
| Codeship API | developer-tools | 14 | Authenticate to Codeship, trigger and inspect builds, and read pipelines, services, and steps for Codeship Basic and Pro projects. |
| CloudBees CI REST API | developer-tools | 13 | Trigger Jenkins-style jobs, monitor builds and queues, retrieve console output, and manage job configurations on a CloudBees CI controller. |

## Which API to use

| Need | API | Why |
| --- | --- | --- |
| Trigger and monitor builds on a self-hosted Jenkins-based controller | ci-api | CloudBees CI exposes Jenkins-compatible job, build, queue, and config.xml endpoints on your own controller instance. |
| Trigger and inspect builds on a hosted SaaS CI service | codeship-api | Codeship runs on CloudBees-hosted machines and exposes projects, builds, and Pro pipeline detail via a JWT-authenticated REST API. |
| Manage CI configuration as code | ci-api | CloudBees CI can read and replace a job's config.xml and create new jobs, which Codeship's project model does not offer. |
| Rotate build secret encryption keys | codeship-api | Codeship exposes an AES key reset endpoint for a project's encrypted environment variables, which CloudBees CI does not provide. |

## Cross-API use cases

### Unified build status dashboard

Aggregate build state from both a self-hosted CloudBees CI controller and hosted Codeship projects into one release dashboard. An agent reads the job list and latest build per job from CloudBees CI and the recent builds per project from Codeship, then reports any failures across both platforms in one view.

Example prompt: Fetch the job list from the CloudBees CI controller and the project builds from Codeship, then report every job or project whose latest build failed

### Cross-platform failure recovery

Automatically respond to failed builds on either platform. On a CloudBees CI failure the agent retrieves the console log and can stop a stuck build, and on a Codeship failure it can restart a build that failed on a transient error, keeping both fleets healthy from one automation.

Example prompt: On a failure event, pull the CloudBees CI console log or restart the Codeship build depending on which platform ran the job

### Migration-window dual triggering

During a migration between hosted Codeship and a self-hosted CloudBees CI controller, trigger the same commit on both platforms and compare results. The agent posts a parameterised build to CloudBees CI and a build to the matching Codeship project, then polls both for status to confirm parity before cutover.

Example prompt: Trigger a build for the same commit on both the CloudBees CI job and the Codeship project, then poll both build results and report any divergence

## Why Jentic

- **Setup:** Wiring each CloudBees API by hand means handling basic auth and Jenkins URL conventions for CloudBees CI and a separate JWT exchange for Codeship. Through Jentic you install Jentic One once, add the CloudBees CI and Codeship APIs from the Jentic directory, store each credential once, and your agent calls both.
- **Permission scoping:** Both APIs put identifiers in the URL path: CloudBees CI uses the job name and Codeship uses organization and project ids. Your own rules can pin an agent to a single job or project and to a chosen set of operations, so triggering a build is allowed while stopping a build or resetting an encryption key stays out of reach unless you include it.
- **Credential handling:** Your CloudBees CI username and API token and your Codeship username, password, and JWT are stored encrypted by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** An agent searches the Jentic directory by intent such as 'trigger a CloudBees CI build' or 'restart a Codeship build', and Jentic returns the matching operation with its parameter schema so the agent calls the right endpoint without reading Jenkins or Codeship reference docs.

## Related vendors

- **CircleCI** — Hosted CI/CD platform with config-as-code, an alternative for greenfield SaaS-hosted pipelines.
- **Buildkite** — Hybrid CI with a hosted control plane and self-hosted build agents, overlapping both CloudBees offerings.
- **GitHub** — Source-of-truth for code that drives CloudBees CI and Codeship builds; pairs for PR-triggered pipelines.

## FAQ

### What is the difference between the two CloudBees CI APIs in the directory?

CloudBees CI is the enterprise distribution of Jenkins that you run on your own controller, and its API is Jenkins-compatible with job, build, queue, and config.xml endpoints. Codeship is a hosted SaaS CI/CD service that CloudBees acquired, with a JWT-authenticated API for projects, builds, and Pro pipeline detail. Choose CloudBees CI for self-hosted Jenkins workloads and Codeship for cloud-hosted pipelines.

### Can one credential authenticate to both CloudBees APIs?

No. CloudBees CI uses HTTP basic auth with a username and API token generated from the user profile page, while Codeship exchanges a username and password at its auth endpoint for a JWT bearer token. Each API requires its own credential, stored separately.

### Why does Jentic publish these specs rather than CloudBees?

CloudBees does not publish official OpenAPI specifications for either CloudBees CI or Codeship. Jentic generates and maintains both specs, validates them against the live APIs, and keeps them agent-ready so tooling can call the endpoints with structured parameters.

### Can an agent manage both self-hosted and hosted CI from one workflow?

Yes. Because both APIs live in the Jentic directory, an agent can trigger builds, read status, and recover failures on a self-hosted CloudBees CI controller and on hosted Codeship projects within a single automation, which is useful for teams running both during a migration or in parallel.

### Do these APIs cover source control or deployment?

No. Both APIs are scoped to CI/CD build operations. They do not host source code, store artifacts, or orchestrate deployments. Pair them with a source-control API such as GitHub to react to pull request events and then trigger the corresponding build.

### Can an agent manage CI configuration as code?

CloudBees CI supports it directly: an agent can read a job's config.xml, replace it, and create new jobs from an XML template, which is the standard Jenkins pattern for keeping pipeline definitions reviewable. Codeship works at the project level and exposes project creation and configuration but not raw config-as-code files.