Artifactory Docker Registry API

openapi: 3.1.0
info:
  title: JFrog Artifactory Docker Registry API
  description: >-
    Docker Registry HTTP API V2 implementation in JFrog Artifactory. Provides
    endpoints for managing Docker images including pushing and pulling layers
    and manifests, listing tags, and managing repositories. Artifactory acts
    as a fully compliant Docker registry with additional features like
    promotion and property management.
  version: v2
  contact:
    name: JFrog Support
    url: https://jfrog.com/support/
    email: [email protected]
  license:
    name: Proprietary
    url: https://jfrog.com/terms-of-service/
  termsOfService: https://jfrog.com/terms-of-service/
externalDocs:
  description: JFrog Artifactory Docker Registry Documentation
  url: https://jfrog.com/help/r/jfrog-artifactory-documentation/docker-registry
servers:
  - url: https://{server}
    description: JFrog Artifactory Docker Registry
    variables:
      server:
        default: myserver.jfrog.io
        description: Your JFrog Platform deployment URL
security:
  - BearerAuth: []
  - BasicAuth: []
tags:
  - name: Artifactory Extensions
    description: Artifactory-specific Docker API extensions
  - name: Base
    description: API version check and health
  - name: Blobs
    description: Push and pull image layers (blobs)
  - name: Catalog
    description: List available repositories
  - name: Manifests
    description: Push and pull image manifests
paths:
  /v2/:
    get:
      operationId: checkApiVersion
      summary: JFrog Artifactory API Version Check
      description: >-
        Check that the registry implements the Docker Registry HTTP API V2.
        Returns 200 OK if the registry supports V2.
      tags:
        - Base
      security: []
      responses:
        '200':
          description: Registry supports V2 API
          headers:
            Docker-Distribution-Api-Version:
              description: The API version
              schema:
                type: string
                example: registry/2.0
        '401':
          description: Authentication required
          headers:
            WWW-Authenticate:
              description: Authentication challenge
              schema:
                type: string
  /v2/_catalog:
    get:
      operationId: listRepositories
      summary: JFrog Artifactory List Repositories
      description: Returns a list of repositories available in the registry.
      tags:
        - Catalog
      parameters:
        - name: n
          in: query
          description: Maximum number of entries to return
          schema:
            type: integer
        - name: last
          in: query
          description: Last repository name for pagination
          schema:
            type: string
      responses:
        '200':
          description: Repository list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepositoryCatalog'
          headers:
            Link:
              description: RFC5988 link to next page of results
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/{name}/tags/list:
    get:
      operationId: listTags
      summary: JFrog Artifactory List Image Tags
      description: Returns the list of tags for a specific image repository.
      tags: []
      parameters:
        - $ref: '#/components/parameters/ImageName'
        - name: n
          in: query
          description: Maximum number of entries to return
          schema:
            type: integer
        - name: last
          in: query
          description: Last tag name for pagination
          schema:
            type: string
      responses:
        '200':
          description: Tag list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagList'
          headers:
            Link:
              description: RFC5988 link to next page of results
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/{name}/manifests/{reference}:
    get:
      operationId: getManifest
      summary: JFrog Artifactory Get Image Manifest
      description: >-
        Retrieves the manifest for an image identified by name and reference
        (tag or digest). The Accept header determines the manifest format returned.
      tags:
        - Manifests
      parameters:
        - $ref: '#/components/parameters/ImageName'
        - $ref: '#/components/parameters/Reference'
        - name: Accept
          in: header
          description: Acceptable manifest media types
          schema:
            type: string
            example: application/vnd.docker.distribution.manifest.v2+json
      responses:
        '200':
          description: Image manifest
          content:
            application/vnd.docker.distribution.manifest.v2+json:
              schema:
                $ref: '#/components/schemas/ManifestV2'
            application/vnd.docker.distribution.manifest.list.v2+json:
              schema:
                $ref: '#/components/schemas/ManifestList'
            application/vnd.oci.image.manifest.v1+json:
              schema:
                $ref: '#/components/schemas/ManifestV2'
            application/vnd.oci.image.index.v1+json:
              schema:
                $ref: '#/components/schemas/ManifestList'
          headers:
            Docker-Content-Digest:
              description: Digest of the manifest
              schema:
                type: string
                example: sha256:abc123...
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: putManifest
      summary: JFrog Artifactory Push Image Manifest
      description: >-
        Pushes an image manifest to the registry. The manifest must reference
        layers that have already been uploaded.
      tags:
        - Manifests
      parameters:
        - $ref: '#/components/parameters/ImageName'
        - $ref: '#/components/parameters/Reference'
      requestBody:
        required: true
        content:
          application/vnd.docker.distribution.manifest.v2+json:
            schema:
              $ref: '#/components/schemas/ManifestV2'
          application/vnd.oci.image.manifest.v1+json:
            schema:
              $ref: '#/components/schemas/ManifestV2'
      responses:
        '201':
          description: Manifest uploaded successfully
          headers:
            Location:
              description: URL of the uploaded manifest
              schema:
                type: string
            Docker-Content-Digest:
              description: Digest of the uploaded manifest
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteManifest
      summary: JFrog Artifactory Delete Image Manifest
      description: Deletes the manifest identified by name and reference (must be a digest).
      tags:
        - Manifests
      parameters:
        - $ref: '#/components/parameters/ImageName'
        - name: reference
          in: path
          required: true
          description: Manifest digest
          schema:
            type: string
            example: sha256:abc123...
      responses:
        '202':
          description: Manifest deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/{name}/blobs/{digest}:
    get:
      operationId: getBlob
      summary: JFrog Artifactory Get Blob (Layer)
      description: Retrieves a blob (layer) from the registry by its digest.
      tags:
        - Blobs
      parameters:
        - $ref: '#/components/parameters/ImageName'
        - name: digest
          in: path
          required: true
          description: Blob digest
          schema:
            type: string
            example: sha256:abc123...
      responses:
        '200':
          description: Blob content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          headers:
            Docker-Content-Digest:
              description: Digest of the blob
              schema:
                type: string
            Content-Length:
              description: Size of the blob in bytes
              schema:
                type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    head:
      operationId: checkBlobExists
      summary: JFrog Artifactory Check Blob Exists
      description: Checks if a blob exists in the registry without downloading it.
      tags:
        - Blobs
      parameters:
        - $ref: '#/components/parameters/ImageName'
        - name: digest
          in: path
          required: true
          description: Blob digest
          schema:
            type: string
      responses:
        '200':
          description: Blob exists
          headers:
            Docker-Content-Digest:
              description: Digest of the blob
              schema:
                type: string
            Content-Length:
              description: Size of the blob in bytes
              schema:
                type: integer
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteBlob
      summary: JFrog Artifactory Delete Blob
      description: Deletes a blob from the registry by its digest.
      tags:
        - Blobs
      parameters:
        - $ref: '#/components/parameters/ImageName'
        - name: digest
          in: path
          required: true
          description: Blob digest
          schema:
            type: string
      responses:
        '202':
          description: Blob deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/{name}/blobs/uploads/:
    post:
      operationId: initiateUpload
      summary: JFrog Artifactory Initiate Blob Upload
      description: >-
        Initiates a blob upload. Returns a session URL for uploading data.
        Supports monolithic upload via digest query parameter or chunked
        upload via the returned upload URL.
      tags:
        - Blobs
      parameters:
        - $ref: '#/components/parameters/ImageName'
        - name: digest
          in: query
          description: >-
            If provided with mount, attempts cross-repo mount.
            If provided alone with body, performs monolithic upload.
          schema:
            type: string
        - name: mount
          in: query
          description: Digest of blob to mount from another repository
          schema:
            type: string
        - name: from
          in: query
          description: Source repository for cross-repo mount
          schema:
            type: string
      responses:
        '202':
          description: Upload session started
          headers:
            Location:
              description: URL for the upload session
              schema:
                type: string
            Docker-Upload-UUID:
              description: Unique identifier for the upload session
              schema:
                type: string
            Range:
              description: Range of bytes received so far
              schema:
                type: string
        '201':
          description: Blob successfully mounted from another repository
          headers:
            Location:
              description: URL of the mounted blob
              schema:
                type: string
            Docker-Content-Digest:
              description: Digest of the mounted blob
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/{name}/blobs/uploads/{uuid}:
    patch:
      operationId: uploadBlobChunk
      summary: JFrog Artifactory Upload Blob Chunk
      description: Uploads a chunk of data for the specified upload session.
      tags:
        - Blobs
      parameters:
        - $ref: '#/components/parameters/ImageName'
        - name: uuid
          in: path
          required: true
          description: Upload session UUID
          schema:
            type: string
        - name: Content-Range
          in: header
          description: Range of bytes being uploaded
          schema:
            type: string
            example: 0-1023
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '202':
          description: Chunk accepted
          headers:
            Location:
              description: URL for the next upload
              schema:
                type: string
            Docker-Upload-UUID:
              description: Upload session UUID
              schema:
                type: string
            Range:
              description: Range of bytes received
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: completeUpload
      summary: JFrog Artifactory Complete Blob Upload
      description: >-
        Completes the upload session and creates the blob. The final
        chunk may be included in this request.
      tags:
        - Blobs
      parameters:
        - $ref: '#/components/parameters/ImageName'
        - name: uuid
          in: path
          required: true
          description: Upload session UUID
          schema:
            type: string
        - name: digest
          in: query
          required: true
          description: Expected digest of the complete blob
          schema:
            type: string
      requestBody:
        description: Optional final chunk of data
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: Blob upload completed
          headers:
            Location:
              description: URL of the completed blob
              schema:
                type: string
            Docker-Content-Digest:
              description: Digest of the uploaded blob
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: cancelUpload
      summary: JFrog Artifactory Cancel Blob Upload
      description: Cancels an in-progress blob upload.
      tags:
        - Blobs
      parameters:
        - $ref: '#/components/parameters/ImageName'
        - name: uuid
          in: path
          required: true
          description: Upload session UUID
          schema:
            type: string
      responses:
        '204':
          description: Upload cancelled
        '404':
          $ref: '#/components/responses/NotFound'
  /api/docker/{repoKey}/v2/promote:
    post:
      operationId: promoteDockerImage
      summary: JFrog Artifactory Promote Docker Image
      description: >-
        Artifactory-specific extension to promote a Docker image from one
        repository to another. This is useful for promoting images through
        staging environments (e.g., dev to staging to production).
      tags:
        - Artifactory Extensions
      parameters:
        - name: repoKey
          in: path
          required: true
          description: Source repository key
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DockerPromoteRequest'
      responses:
        '200':
          description: Image promoted successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Docker token authentication. Obtain a token from the authentication
        service endpoint returned in the WWW-Authenticate header.
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using Artifactory credentials
  parameters:
    ImageName:
      name: name
      in: path
      required: true
      description: >-
        Docker image name, which may include multiple path components
        (e.g., library/nginx or myproject/myimage)
      schema:
        type: string
        example: library/nginx
    Reference:
      name: reference
      in: path
      required: true
      description: Image tag or digest reference
      schema:
        type: string
        example: latest
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    RepositoryCatalog:
      type: object
      properties:
        repositories:
          type: array
          items:
            type: string
          description: List of repository names available
          example:
            - library/nginx
            - library/alpine
            - myproject/myimage
    TagList:
      type: object
      properties:
        name:
          type: string
          description: Image repository name
          example: library/nginx
        tags:
          type: array
          items:
            type: string
          description: List of available tags
          example:
            - latest
            - "1.25"
            - "1.25.3"
            - alpine
    ManifestV2:
      type: object
      description: Docker Image Manifest V2, Schema 2 (or OCI Image Manifest)
      properties:
        schemaVersion:
          type: integer
          description: Schema version (always 2)
          example: 2
        mediaType:
          type: string
          description: Media type of the manifest
          example: application/vnd.docker.distribution.manifest.v2+json
        config:
          type: object
          description: Image configuration object reference
          properties:
            mediaType:
              type: string
              description: Media type of the config object
              example: application/vnd.docker.container.image.v1+json
            size:
              type: integer
              description: Size in bytes
            digest:
              type: string
              description: Content digest
              example: sha256:abc123...
        layers:
          type: array
          description: List of layer references
          items:
            type: object
            properties:
              mediaType:
                type: string
                description: Media type of the layer
                example: application/vnd.docker.image.rootfs.diff.tar.gzip
              size:
                type: integer
                description: Size in bytes
              digest:
                type: string
                description: Content digest
                example: sha256:def456...
    ManifestList:
      type: object
      description: Docker Manifest List (or OCI Image Index) for multi-arch images
      properties:
        schemaVersion:
          type: integer
          description: Schema version (always 2)
          example: 2
        mediaType:
          type: string
          description: Media type
          example: application/vnd.docker.distribution.manifest.list.v2+json
        manifests:
          type: array
          description: List of platform-specific manifests
          items:
            type: object
            properties:
              mediaType:
                type: string
                description: Media type of the referenced manifest
              size:
                type: integer
                description: Size of the referenced manifest
              digest:
                type: string
                description: Digest of the referenced manifest
              platform:
                type: object
                properties:
                  architecture:
                    type: string
                    description: CPU architecture
                    example: amd64
                  os:
                    type: string
                    description: Operating system
                    example: linux
                  variant:
                    type: string
                    description: Architecture variant
                    example: v8
    DockerPromoteRequest:
      type: object
      required:
        - targetRepo
        - dockerRepository
      properties:
        targetRepo:
          type: string
          description: Target repository key to promote to
          example: docker-prod-local
        dockerRepository:
          type: string
          description: Docker repository name (image path)
          example: myproject/myimage
        targetDockerRepository:
          type: string
          description: >-
            Target Docker repository name. If not specified, uses the same
            name as the source.
          example: myproject/myimage
        tag:
          type: string
          description: Tag to promote. If not specified, all tags are promoted.
          example: "1.0.0"
        targetTag:
          type: string
          description: Target tag name. If not specified, uses the same tag.
          example: latest
        copy:
          type: boolean
          description: >-
            If true, copies instead of moves. Default is false (move).
          default: false
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: Error code
              message:
                type: string
                description: Error message
              detail:
                type: string
                description: Additional error details