Skip to main content
Use the CI/CD API to build an immutable release of a project, deploy it to an environment, and promote it to a higher environment. The API needs no Studio login and no Git integration.

Prerequisites

  • A platform API key with a client ID (plt-…) and a client secret (abl_…).
  • A project ID that’s in the key’s allowed projects.
  • The cicd.release.create, cicd.deploy, and cicd.promote scopes on the key.
  • Authority on each environment you deploy or promote to. Call Get caller identity to check.

Endpoints

Workflow

To deploy content from another workspace, first move it into the target project with the project import and export API. Then build the release from a project snapshot.
  1. Exchange the platform API key for a Bearer token. Send the token in the Authorization: Bearer <token> header on every other call. The token expires after 900 seconds by default.
  2. Call whoami to confirm the environments you can deploy and promote to.
  3. Create a release. Use source.kind="project_snapshot" to build from the project’s current content, or git to build from a branch, tag, or commit.
  4. Poll the release until its status is ready.
  5. Create a deployment with the releaseId and a target environment: dev, staging, or production.
  6. Poll the deployment until its status is active.
  7. Promote the active deployment to a higher environment.

Behavior to know

  • A release is immutable and independent of the environment. Promotion moves the same release to the target environment.
  • Release builds, deployments, and promotions run asynchronously. Use the status endpoints to track them.
  • The API checks environment authority at deploy and promote time, not when you build a release.
  • A qualification gate runs on every deploy and promote. To bypass it, set bypassQualificationGate and bypassReason. The key needs the cicd.gate.bypass scope.