> ## 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.

# Promote deployment

> Moves the SAME immutable, environment-agnostic release artifact into `targetEnvironment`, re-checking that environment's qualification gate. Requires `cicd.promote` plus authority on the target environment; the source deployment must be "active". This is the step the ticket's "Current Behavior" section says has no reachable public path once content arrived via the Import API instead of Artemis Git — reachable here because the release was built with source.kind="project_snapshot".

Promote an active deployment's release to a higher environment.


## OpenAPI

````yaml agent-platform/api-specs/project-deploy-promote.yaml post /api/cicd/v1/projects/{projectId}/deployments/{deploymentId}/promote
openapi: 3.1.0
info:
  title: Public Project Deploy & Promote API
  version: 1.0.0
  description: >-
    The public, platform-API-key-usable path to deploy a project's CURRENT
    content to an environment and promote it through higher environments, with
    no Studio/user login and no Git dependency. Canonical source:
    docs/api/artemis-cicd-openapi.yaml (full CI/CD API — git, webhooks, eval
    gates, rollback, audit packs). This file is a focused subset for the "import
    -> release -> deploy -> promote" flow:

      1. Move project content between workspaces with the Public Project
         Import/Export API (docs/specs/public-project-import-export-api.openapi.yaml).
      2. Build an immutable release from the imported project's CURRENT content
         with source.kind="project_snapshot".
      3. Deploy that release to an environment, then promote it to a higher one.

    Auth differs from the Import/Export API: there is no raw `x-api-key``
    header. A platform key (`client_secret``) is exchanged for a short-lived
    Bearer JWT via the OAuth2 client-credentials grant below, and that JWT is
    sent as `Authorization: Bearer <token>` on every other call.
servers:
  - url: /
security: []
paths:
  /api/cicd/v1/projects/{projectId}/deployments/{deploymentId}/promote:
    post:
      summary: Promote an active deployment's release to a higher environment.
      description: >-
        Moves the SAME immutable, environment-agnostic release artifact into
        `targetEnvironment`, re-checking that environment's qualification gate.
        Requires `cicd.promote` plus authority on the target environment; the
        source deployment must be "active". This is the step the ticket's
        "Current Behavior" section says has no reachable public path once
        content arrived via the Import API instead of Artemis Git — reachable
        here because the release was built with source.kind="project_snapshot".
      operationId: promoteDeployment
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/DeploymentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromoteRequest'
      responses:
        '202':
          description: Promotion started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentJobResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            ENV_SCOPE_VIOLATION — the key/token lacks authority for
            targetEnvironment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CicdErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            DEPLOYMENT_NOT_PROMOTABLE (source deployment isn't active) or a
            failed qualification gate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CicdErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - BearerAuth: []
components:
  parameters:
    ProjectId:
      name: projectId
      in: path
      required: true
      schema:
        type: string
      description: UUID v7; must be in the key/token's projectIds.
    DeploymentId:
      name: deploymentId
      in: path
      required: true
      schema:
        type: string
  schemas:
    PromoteRequest:
      type: object
      required:
        - targetEnvironment
      additionalProperties: false
      properties:
        targetEnvironment:
          type: string
          enum:
            - dev
            - staging
            - production
        bypassQualificationGate:
          type: boolean
          description: Requires scope cicd.gate.bypass.
        bypassReason:
          type: string
    DeploymentJobResponse:
      type: object
      required:
        - success
        - deploymentId
        - jobId
      properties:
        success:
          type: boolean
        deploymentId:
          type: string
          description: Id of the (new) deployment this action created.
        jobId:
          type: string
          description: '`cicd-deploy-<deploymentId>`.'
        statusUrl:
          type: string
        jobStatusUrl:
          type: string
    CicdErrorResponse:
      type: object
      required:
        - success
        - error
      description: Standard CI/CD error envelope, used for 400/403/404/409/503.
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: >-
                Codes relevant to this flow: PROJECT_NOT_FOUND,
                VALIDATION_ERROR, TRANSFER_SOURCE_INVALID,
                PROJECT_SNAPSHOT_UNAVAILABLE, RELEASE_STORAGE_NOT_SHARED,
                RELEASE_ARTIFACT_UNAVAILABLE, AGENTIC_DRAFT_NOT_ACKNOWLEDGED,
                AGENTIC_HOLD_UNAVAILABLE, RELEASE_SOURCE_EXPIRED,
                RELEASE_NOT_FOUND, RELEASE_NOT_READY, RELEASE_NOT_DEPLOYABLE,
                RELEASE_VERSION_CONFLICT, CONTENT_INTEGRITY_MISMATCH,
                DEPLOYMENT_NOT_FOUND, DEPLOYMENT_NOT_PROMOTABLE,
                QUALIFICATION_GATE_FAILED, BYPASS_REASON_REQUIRED,
                ENV_SCOPE_VIOLATION, SCOPE_VIOLATION, FORBIDDEN, NOT_FOUND,
                RATE_LIMITED, INTERNAL_ERROR. Full enum in
                docs/api/artemis-cicd-openapi.yaml.
            message:
              type: string
            details:
              nullable: true
            retryable:
              type: boolean
            requestId:
              type: string
              description: Correlates with the `X-Request-ID` response header.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
      description: Plain error envelope used for 401/500 across this API.
  responses:
    Unauthorized:
      description: Authentication failure
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Concealed not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CicdErrorResponse'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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