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

# Cloudbees Codeship API

Jentic publishes the only available OpenAPI specification for Codeship API, keeping it validated and agent-ready. Codeship API v2 is the REST interface for the Codeship SaaS CI/CD platform, now part of CloudBees. Endpoints cover authentication via username and password to obtain a JWT, listing and managing projects under an organization, triggering and inspecting builds, restarting or stopping a running build, and reading the build's pipelines, services, and steps for both Basic and Pro project types. Resources are scoped to an organization UUID returned in the auth response.

## For AI agents

Authenticate to Codeship, trigger and inspect builds, and read pipelines, services, and steps for Codeship Basic and Pro projects.

## Scope

Does not handle source-control hosting, artifact storage, or Jenkins controller management - use for triggering and inspecting Codeship Basic and Pro builds only.

## Capabilities

- Exchange username and password for a JWT bearer token via /auth
- List and create projects under a Codeship organization
- Read a project's configuration including AES key for encrypted env vars
- Trigger a new build for a project on a specific commit or branch
- Stop or restart an in-flight build
- Read per-build pipelines, services, and steps for Pro projects
- Reset a project's AES encryption key for environment variables

## Use cases

### Build Triggering From External Systems

Trigger Codeship builds from chatops, scheduling tools, or release-management software by calling POST `/organizations/{organization_uuid}/projects/{project_uuid}/builds` with the target commit SHA or branch. The endpoint queues the build and returns its UUID, which downstream tooling can poll for status. This replaces manual 'rebuild' clicks in the Codeship UI for routine release flows.

Example prompt: POST a build for project_uuid on branch=main with the latest commit SHA, then poll the build UUID for status

### Build Status Aggregation

Aggregate build status across Codeship projects into a release dashboard. GET `/organizations/{organization_uuid}/projects/{project_uuid}/builds` returns recent builds and GET `/organizations/{organization_uuid}/projects/{project_uuid}/builds/{build_uuid}` returns per-build detail. For Codeship Pro projects, the pipelines, services, and steps endpoints expose the full DAG so a dashboard can highlight which step in the pipeline failed.

Example prompt: Iterate projects, fetch the latest build for each, and report any whose status is failed in the past 24 hours

### Failure Recovery Automations

Automatically restart a build that failed due to flake or upstream outage by calling `/builds/{build_uuid}/restart`, or stop a runaway build that would otherwise consume the parallel slot via `/builds/{build_uuid}/stop.` Combined with status polling, this is the standard self-healing pattern for CI fleets that run thousands of builds per week.

Example prompt: If a build's status is 'error' and the failure log indicates a network timeout, POST to `/builds/{build_uuid}/restart`

### Secret Rotation

Rotate the AES encryption key used by a Codeship project for encrypted environment variables. POST `/organizations/{organization_uuid}/projects/{project_uuid}/reset_aes_key` issues a new key, which the team then uses to re-encrypt the project's secrets file. This is the canonical key-rotation flow when an engineer with access leaves or a key is suspected to be compromised.

Example prompt: Call /reset_aes_key on the project and then re-encrypt the local env.encrypted file with the new key

### Agent-Driven CI Operations via Jentic

AI assistants for platform teams can answer 'restart the failed payment-service build' by searching Jentic for an intent and executing the matching Codeship operation. The Codeship JWT lives in your Jentic One instance and a scoped credential is issued per call, so the long-lived auth response never enters the agent's context.

Example prompt: Search Jentic for 'restart codeship build', load the /restart operation, and execute it for the named build_uuid

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/auth` | Exchange credentials for a JWT |
| GET | `/organizations/{organization_uuid}/projects` | List projects in an organization |
| POST | `/organizations/{organization_uuid}/projects/{project_uuid}/builds` | Trigger a build |
| GET | `/organizations/{organization_uuid}/projects/{project_uuid}/builds/{build_uuid}` | Get a build by UUID |
| POST | `/organizations/{organization_uuid}/projects/{project_uuid}/builds/{build_uuid}/stop` | Stop a running build |
| POST | `/organizations/{organization_uuid}/projects/{project_uuid}/builds/{build_uuid}/restart` | Restart a build |
| GET | `/organizations/{organization_uuid}/projects/{project_uuid}/builds/{build_uuid}/pipelines` | List pipelines for a Pro build |
| POST | `/organizations/{organization_uuid}/projects/{project_uuid}/reset_aes_key` | Rotate the project's AES encryption key |

## Key resources

- **auth** — Username and password exchange for a JWT
- **projects** — Project listing, creation, and configuration under an organization
- **builds** — Triggered builds with status and lifecycle controls
- **pipelines** — Pipelines that ran in a Pro build
- **services** — Services that ran in a Pro build
- **steps** — Steps inside a Pro build's pipelines

## Why Jentic

- **Setup:** Wiring the Codeship API by hand means exchanging your username and password at /auth for a JWT, refreshing that bearer token, and pointing calls at api.codeship.com/v2 yourself. Through Jentic you install once, import the Codeship API from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** Codeship puts the organization and project ids in the URL path (`/organizations/{organization_uuid}/projects/{project_uuid}/...`), so a rule can pin your agent to one project: it can trigger, read, and restart builds there and nothing else. You choose the operations it may call, so stopping a build or resetting the AES key is only in reach if you include it.
- **Credential handling:** Your Codeship username, password, and the resulting JWT are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'trigger a Codeship build' or 'restart a build', and Jentic returns the matching operation with its parameter schema so the agent calls the right endpoint without reading the Codeship reference docs.

## 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.
- **CloudBees CI** — Enterprise Jenkins controller from the same vendor.
- **GitHub** — Source-of-truth for code that drives Codeship builds.

## FAQ

### Why is there no official OpenAPI spec for Codeship API?

CloudBees does not publish an OpenAPI specification for the Codeship API. Jentic generates and maintains this spec so that AI agents and developers can call Codeship 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 Codeship API use?

Codeship uses a JWT bearer token. POST /auth with the user's Codeship username and password returns a JWT plus the organization UUIDs the user belongs to. Through Jentic, credentials and the resulting JWT live in the vault and a scoped bearer token is issued per call.

### Can I restart a failed build with this API?

Yes. POST `/organizations/{organization_uuid}/projects/{project_uuid}/builds/{build_uuid}/restart` re-runs the same build without requiring a new commit, which is useful for transient failures. POST /stop on the same path cancels a build that is still running.

### What are the rate limits for the Codeship API?

Codeship does not publish an explicit rate limit in this spec. Treat the API as low-volume control plane traffic - back off on 429 responses and avoid bursting more than a few requests per second per JWT, especially for build creation.

### How do I trigger a Codeship build through Jentic?

Run pip install jentic, search for 'trigger a codeship build', load the POST `/organizations/{organization_uuid}/projects/{project_uuid}/builds` operation, then execute with the target ref or commit SHA. The call returns the new build UUID.

### Does this API expose pipelines and steps for Codeship Pro?

Yes. `/builds/{build_uuid}/pipelines`, `/builds/{build_uuid}/services`, and `/builds/{build_uuid}/steps` return the per-pipeline DAG, the services Codeship Pro spun up, and the individual steps with their statuses.

### Can I limit what my agent is allowed to do with the Codeship API?

Yes. Because Codeship puts the organization and project ids in the URL path (`/organizations/{organization_uuid}/projects/{project_uuid}/...`), a rule in your self-hosted Jentic One instance can pin your agent to a single project, letting it trigger, read, and restart builds there and nothing else. You decide which operations it may call, so stopping a running build via `/builds/{build_uuid}/stop` or rotating a project's key via /reset_aes_key is only in reach if your own rules include it. The credentials that authorize those calls stay with your Jentic One instance rather than the agent.