JFrog Artifactory Build Promotion API

openapi: 3.2.0
info:
  title: JFrog Artifactory Build Integration Build Promotion API
  description: API for publishing and managing build information from CI/CD systems in JFrog Artifactory. Supports publishing build info, promoting builds between repositories, managing build retention, and querying build details including modules, artifacts, and dependencies.
  version: 7.x
  contact:
    name: JFrog Support
    url: https://jfrog.com/support/
    email: support@jfrog.com
  license:
    name: Proprietary
    url: https://jfrog.com/terms-of-service/
  termsOfService: https://jfrog.com/terms-of-service/
servers:
- url: https://{server}/artifactory
  description: JFrog Artifactory Server
  variables:
    server:
      default: myserver.jfrog.io
      description: Your JFrog Platform deployment URL
security:
- BearerAuth: []
- ApiKeyAuth: []
- BasicAuth: []
tags:
- name: Build Promotion
  description: Promote builds between repositories
paths:
  /api/build/promote/{buildName}/{buildNumber}:
    post:
      operationId: promoteBuild
      summary: Promote Build
      description: Promotes a build by moving or copying the build artifacts and dependencies from a source repository to a target repository. Used to promote builds through staging environments (e.g., from staging to production).
      tags:
      - Build Promotion
      parameters:
      - $ref: '#/components/parameters/BuildName'
      - $ref: '#/components/parameters/BuildNumber'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildPromotionRequest'
      responses:
        '200':
          description: Build promoted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildPromotionResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    BuildNumber:
      name: buildNumber
      in: path
      required: true
      description: The build number (version)
      schema:
        type: string
        example: '123'
    BuildName:
      name: buildName
      in: path
      required: true
      description: The name of the build
      schema:
        type: string
        example: my-application
  responses:
    Unauthorized:
      description: Unauthorized - authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request - invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    BuildPromotionResult:
      type: object
      properties:
        status:
          type: string
          description: Result status
          example: success
        messages:
          type: object
          properties:
            level:
              type: string
              description: Message level
            message:
              type: string
              description: Result message
    BuildPromotionRequest:
      type: object
      required:
      - targetRepo
      properties:
        status:
          type: string
          description: Promotion status label
          example: Released
        comment:
          type: string
          description: Comment for the promotion
          example: Promoted to production
        ciUser:
          type: string
          description: CI user who initiated the promotion
        timestamp:
          type: string
          format: date-time
          description: Promotion timestamp
        properties:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Properties to attach to promoted artifacts
        sourceRepo:
          type: string
          description: Source repository key
          example: libs-staging-local
        targetRepo:
          type: string
          description: Target repository key
          example: libs-release-local
        copy:
          type: boolean
          description: If true, copy artifacts. If false, move artifacts.
          default: false
        artifacts:
          type: boolean
          description: Whether to move/copy build artifacts
          default: true
        dependencies:
          type: boolean
          description: Whether to move/copy build dependencies
          default: false
        failFast:
          type: boolean
          description: Fail on the first error rather than continuing
          default: true
        dryRun:
          type: boolean
          description: Perform a dry run without making changes
          default: false
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: integer
                description: HTTP status code
              message:
                type: string
                description: Error message
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Access token authentication
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-JFrog-Art-Api
      description: API key authentication via header
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication
externalDocs:
  description: JFrog Artifactory Build Integration Documentation
  url: https://jfrog.com/help/r/jfrog-rest-apis/builds