> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Project deploy and promote API overview

> Use the CI/CD API to build releases, deploy projects to dev, staging, and production, and promote deployments to higher environments with a platform API key.

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](https://koreai.mintlify.site/agent-platform/api-reference/cicd-whoami) to check.

## Endpoints

| Task | Help article | Purpose | Required scope |
| :- | :- | :- | :- |
| Authenticate | [Exchange Platform key for JWT token](https://koreai.mintlify.site/agent-platform/api-reference/cicd-tokens) | Exchange a platform API key for a Bearer JWT. | None (unauthenticated) |
| Check access | [Get caller identity](https://koreai.mintlify.site/agent-platform/api-reference/cicd-whoami) | Describe the calling credential, including its environment authority. | |
| Build | [Create release](https://koreai.mintlify.site/agent-platform/api-reference/cicd-releases-create) | Build an immutable release from Git, a project snapshot, or a cross-tenant transfer. | `cicd.release.create` |
| | [Get release](https://koreai.mintlify.site/agent-platform/api-reference/cicd-releases-get) | Poll a release until its status is `ready` or `failed`. | |
| | [List releases](https://koreai.mintlify.site/agent-platform/api-reference/cicd-releases-list) | List releases for the project. | |
| Deploy | [Create deployment](https://koreai.mintlify.site/agent-platform/api-reference/cicd-deployments-create) | Deploy a `ready` release to an environment. | `cicd.deploy` |
| | [Get deployment](https://koreai.mintlify.site/agent-platform/api-reference/cicd-deployments-get) | Get a deployment's status, environment, release, and versions. | |
| | [List deployments](https://koreai.mintlify.site/agent-platform/api-reference/cicd-deployments-list) | List deployments for the project. | |
| Promote | [Promote deployment](https://koreai.mintlify.site/agent-platform/api-reference/cicd-deployments-promote) | Promote an active deployment's release to a higher environment. | `cicd.promote` |

## Workflow

To deploy content from another workspace, first move it into the target project with the [project import and export API](https://koreai.mintlify.site/agent-platform/api-reference/project-import-export-overview.md). 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.