openapi: 3.1.0
info:
  title: JFrog Artifactory Build Integration 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/
externalDocs:
  description: JFrog Artifactory Build Integration Documentation
  url: https://jfrog.com/help/r/jfrog-rest-apis/builds
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 Info
    description: Publish and retrieve build information
  - name: Build Promotion
    description: Promote builds between repositories
  - name: Build Management
    description: List, delete, and manage builds
  - name: Build Diff
    description: Compare build versions
paths:
  /api/build:
    get:
      operationId: listBuilds
      summary: List All Builds
      description: Returns a list of all builds stored in the system.
      tags:
        - Build Management
      responses:
        '200':
          description: List of builds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildsList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/build/{buildName}:
    get:
      operationId: getBuildRuns
      summary: Get Build Runs
      description: Returns a list of all runs (versions) for a specific build name.
      tags:
        - Build Info
      parameters:
        - $ref: '#/components/parameters/BuildName'
      responses:
        '200':
          description: List of build runs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildRuns'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteBuild
      summary: Delete Build
      description: >-
        Deletes a build and all its runs. Optionally deletes the associated
        build artifacts.
      tags:
        - Build Management
      parameters:
        - $ref: '#/components/parameters/BuildName'
        - name: deleteAll
          in: query
          description: If 1, delete all build numbers. If 0, requires buildNumbers param.
          schema:
            type: integer
            enum: [0, 1]
            default: 1
        - name: buildNumbers
          in: query
          description: Comma-separated list of build numbers to delete
          schema:
            type: string
        - name: artifacts
          in: query
          description: If 1, also delete associated build artifacts from repositories
          schema:
            type: integer
            enum: [0, 1]
            default: 0
      responses:
        '200':
          description: Build deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/build/{buildName}/{buildNumber}:
    get:
      operationId: getBuildInfo
      summary: Get Build Information
      description: >-
        Returns detailed build information for a specific build name and number,
        including modules, artifacts, dependencies, and environment variables.
      tags:
        - Build Info
      parameters:
        - $ref: '#/components/parameters/BuildName'
        - $ref: '#/components/parameters/BuildNumber'
        - name: started
          in: query
          description: >-
            Build start time filter in ISO8601 format. Useful when multiple
            builds share the same number.
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Build information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildInfoResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/build:
    put:
      operationId: publishBuildInfo
      summary: Publish Build Info
      description: >-
        Publishes build information to Artifactory. This is typically called
        by CI/CD tools (Jenkins, JFrog CLI, etc.) at the end of a build
        to record the artifacts produced, dependencies consumed, and
        environment details.
      tags:
        - Build Info
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildInfoPublish'
      responses:
        '204':
          description: Build info published successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /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'
  /api/build/rename/{buildName}:
    post:
      operationId: renameBuild
      summary: Rename Build
      description: Renames an existing build to a new name.
      tags:
        - Build Management
      parameters:
        - $ref: '#/components/parameters/BuildName'
        - name: to
          in: query
          required: true
          description: New name for the build
          schema:
            type: string
      responses:
        '200':
          description: Build renamed successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/build/diff/{buildName}/{buildNumber}:
    get:
      operationId: getBuildDiff
      summary: Get Build Diff
      description: >-
        Returns the differences between two build versions, including new
        artifacts, updated artifacts, removed artifacts, new dependencies,
        updated dependencies, removed dependencies, and new/removed properties.
      tags:
        - Build Diff
      parameters:
        - $ref: '#/components/parameters/BuildName'
        - $ref: '#/components/parameters/BuildNumber'
        - name: otherNumber
          in: query
          required: true
          description: The other build number to compare against
          schema:
            type: string
      responses:
        '200':
          description: Build diff result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildDiff'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/build/retention/{buildName}:
    post:
      operationId: setBuildRetention
      summary: Set Build Retention
      description: >-
        Configures retention policies for a build, specifying how many
        builds to keep, minimum build date, and patterns for builds to
        exclude from cleanup.
      tags:
        - Build Management
      parameters:
        - $ref: '#/components/parameters/BuildName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildRetentionConfig'
      responses:
        '200':
          description: Retention configuration applied
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      operationId: getBuildRetention
      summary: Get Build Retention
      description: Returns the retention configuration for a specific build.
      tags:
        - Build Management
      parameters:
        - $ref: '#/components/parameters/BuildName'
      responses:
        '200':
          description: Retention configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildRetentionConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  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
  parameters:
    BuildName:
      name: buildName
      in: path
      required: true
      description: The name of the build
      schema:
        type: string
        example: my-application
    BuildNumber:
      name: buildNumber
      in: path
      required: true
      description: The build number (version)
      schema:
        type: string
        example: "123"
  responses:
    BadRequest:
      description: Bad request - invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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'
  schemas:
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: integer
                description: HTTP status code
              message:
                type: string
                description: Error message
    BuildsList:
      type: object
      properties:
        uri:
          type: string
          format: uri
          description: URI for the builds endpoint
        builds:
          type: array
          items:
            type: object
            properties:
              uri:
                type: string
                description: Relative URI to the build
                example: /my-application
              lastStarted:
                type: string
                format: date-time
                description: When the most recent run started
    BuildRuns:
      type: object
      properties:
        uri:
          type: string
          format: uri
          description: URI for this build
        buildsNumbers:
          type: array
          items:
            type: object
            properties:
              uri:
                type: string
                description: Relative URI to the build number
                example: /123
              started:
                type: string
                format: date-time
                description: When this build run started
    BuildInfoResponse:
      type: object
      properties:
        uri:
          type: string
          format: uri
          description: URI for this build info
        buildInfo:
          $ref: '#/components/schemas/BuildInfo'
    BuildInfo:
      type: object
      properties:
        version:
          type: string
          description: Build info schema version
          example: "1.0.1"
        name:
          type: string
          description: Build name
          example: my-application
        number:
          type: string
          description: Build number
          example: "123"
        type:
          type: string
          description: Build type
          enum:
            - GENERIC
            - MAVEN
            - GRADLE
            - IVY
            - ANT
            - NPM
            - NUGET
            - GO
            - PIP
            - DOCKER
        agent:
          type: object
          description: Build agent information
          properties:
            name:
              type: string
              description: Agent name
              example: Jenkins
            version:
              type: string
              description: Agent version
              example: "2.401"
        buildAgent:
          type: object
          description: Build tool agent information
          properties:
            name:
              type: string
              description: Build agent name
              example: MAVEN
            version:
              type: string
              description: Build agent version
        started:
          type: string
          format: date-time
          description: Build start timestamp
        durationMillis:
          type: integer
          description: Build duration in milliseconds
        principal:
          type: string
          description: The user who triggered the build
        artifactoryPrincipal:
          type: string
          description: Artifactory user associated with the build
        url:
          type: string
          format: uri
          description: CI server URL for this build
        vcsRevision:
          type: string
          description: VCS revision (commit hash)
        vcsUrl:
          type: string
          format: uri
          description: VCS repository URL
        modules:
          type: array
          description: Build modules
          items:
            $ref: '#/components/schemas/BuildModule'
        statuses:
          type: array
          description: Build promotion statuses
          items:
            $ref: '#/components/schemas/BuildStatus'
        properties:
          type: object
          additionalProperties:
            type: string
          description: Build properties (key-value pairs)
    BuildModule:
      type: object
      properties:
        id:
          type: string
          description: Module identifier
          example: com.example:my-module:1.0.0
        artifacts:
          type: array
          description: Artifacts produced by this module
          items:
            type: object
            properties:
              type:
                type: string
                description: Artifact type
                example: jar
              sha1:
                type: string
                description: SHA-1 checksum
              sha256:
                type: string
                description: SHA-256 checksum
              md5:
                type: string
                description: MD5 checksum
              name:
                type: string
                description: Artifact name
                example: my-module-1.0.0.jar
        dependencies:
          type: array
          description: Dependencies consumed by this module
          items:
            type: object
            properties:
              type:
                type: string
                description: Dependency type
              sha1:
                type: string
                description: SHA-1 checksum
              sha256:
                type: string
                description: SHA-256 checksum
              md5:
                type: string
                description: MD5 checksum
              id:
                type: string
                description: Dependency identifier
                example: org.apache.commons:commons-lang3:3.12.0
              scopes:
                type: array
                items:
                  type: string
                description: Dependency scopes
                example:
                  - compile
    BuildStatus:
      type: object
      properties:
        status:
          type: string
          description: Promotion status name
          example: Released
        comment:
          type: string
          description: Status comment
        repository:
          type: string
          description: Target repository for the promotion
        timestamp:
          type: string
          format: date-time
          description: When the status was applied
        user:
          type: string
          description: User who applied the status
        ciUser:
          type: string
          description: CI user who triggered the promotion
    BuildInfoPublish:
      type: object
      required:
        - version
        - name
        - number
        - started
      properties:
        version:
          type: string
          description: Build info schema version
          example: "1.0.1"
        name:
          type: string
          description: Build name
          example: my-application
        number:
          type: string
          description: Build number
          example: "123"
        started:
          type: string
          format: date-time
          description: Build start timestamp
        type:
          type: string
          description: Build type
          enum:
            - GENERIC
            - MAVEN
            - GRADLE
            - IVY
            - ANT
            - NPM
            - NUGET
            - GO
            - PIP
            - DOCKER
        agent:
          type: object
          properties:
            name:
              type: string
            version:
              type: string
        buildAgent:
          type: object
          properties:
            name:
              type: string
            version:
              type: string
        durationMillis:
          type: integer
          description: Build duration in milliseconds
        principal:
          type: string
          description: User who triggered the build
        url:
          type: string
          format: uri
          description: CI server URL
        vcsRevision:
          type: string
          description: VCS revision
        vcsUrl:
          type: string
          format: uri
          description: VCS repository URL
        modules:
          type: array
          items:
            $ref: '#/components/schemas/BuildModule'
        properties:
          type: object
          additionalProperties:
            type: string
          description: Build-level properties
        buildDependencies:
          type: array
          description: Other builds this build depends on
          items:
            type: object
            properties:
              name:
                type: string
                description: Dependency build name
              number:
                type: string
                description: Dependency build number
              started:
                type: string
                format: date-time
                description: Dependency build start time
    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
    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
    BuildDiff:
      type: object
      properties:
        artifacts:
          type: object
          properties:
            new:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  sha1:
                    type: string
                  md5:
                    type: string
            updated:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  sha1:
                    type: string
                  md5:
                    type: string
            removed:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  sha1:
                    type: string
                  md5:
                    type: string
            unchanged:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  sha1:
                    type: string
                  md5:
                    type: string
        dependencies:
          type: object
          properties:
            new:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  sha1:
                    type: string
                  md5:
                    type: string
            updated:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  sha1:
                    type: string
                  md5:
                    type: string
            removed:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  sha1:
                    type: string
                  md5:
                    type: string
            unchanged:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  sha1:
                    type: string
                  md5:
                    type: string
        properties:
          type: object
          properties:
            new:
              type: object
              additionalProperties:
                type: string
            updated:
              type: object
              additionalProperties:
                type: string
            removed:
              type: object
              additionalProperties:
                type: string
            unchanged:
              type: object
              additionalProperties:
                type: string
    BuildRetentionConfig:
      type: object
      properties:
        deleteBuildArtifacts:
          type: boolean
          description: Whether to delete artifacts when the build is cleaned up
          default: false
        count:
          type: integer
          description: Maximum number of builds to keep (-1 means unlimited)
          example: 100
        minimumBuildDate:
          type: string
          format: date-time
          description: Delete builds older than this date
        buildNumbersNotToBeDiscarded:
          type: array
          items:
            type: string
          description: Build numbers that should never be deleted
          example:
            - "1.0.0"
            - "2.0.0"