JFrog Artifactory Build Promotion API

openapi: 3.2.0
info:
  title: JFrog Artifactory Query Language (AQL) AQL Search Build Promotion API
  description: Advanced search API using Artifactory Query Language (AQL), a SQL-like query language for finding and filtering artifacts, builds, and entries in JFrog Artifactory. AQL provides powerful querying capabilities including domain queries, field filtering, sorting, limiting, and inclusion of related entities.
  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:
  responses:
    Unauthorized:
      description: Unauthorized - authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request - invalid input
      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'
  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
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: integer
                description: HTTP status code
              message:
                type: string
                description: Error 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
  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
  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: Artifactory Query Language Documentation
  url: https://jfrog.com/help/r/jfrog-artifactory-documentation/artifactory-query-language