Initiate blob upload or attempt cross-repository blob mount Run in API Explorer

POST /v2/{name}/blobs/uploads/

Initiate an upload session for a blob (layer or config) in a repository.

This is the first step in uploading a blob. It returns a Location URL where the blob can be uploaded using PATCH (chunked) or PUT (monolithic).

Instead of uploading a blob, a client may attempt to mount a blob from another repository (if it has read access) by including the mount and from query parameters.

If successful, the registry responds with 201 Created and the blob is reused without re-upload.

If the mount fails, the upload proceeds as usual and returns a 202 Accepted.

You must authenticate with push access to the target repository.

Headers

  • Authorization string Required

    Bearer token for authentication with push scope

Path parameters

  • name string Required

    Name of the target repository

Query parameters

  • mount string

    Digest of the blob to mount from another repository

  • from string

    Source repository to mount the blob from

Responses

  • 201

    Blob successfully mounted from another repository.

    Hide headers attributes Show headers attributes
    • Location string

      URL where the mounted blob is accessible

    • Docker-Content-Digest string

      Canonical digest of the mounted blob

    • Content-Length integer

      Always zero

  • 202

    Upload initiated successfully (fallback if mount fails).

    Hide headers attributes Show headers attributes
    • Location string

      Upload location URL for PATCH or PUT requests

    • Docker-Upload-UUID string

      Server-generated UUID for the upload session

    • Range string

      Current upload byte range (typically 0-0 at init)

    • Content-Length integer

      Always zero

  • 401

    Authentication required.

  • 403

    Access denied.

  • 404

    Repository not found.

  • 429

    Too many requests.

POST /v2/{name}/blobs/uploads/ 
# Initiate a standard blob upload session
curl -i -X POST \
  -H "Authorization: Bearer $TOKEN" \
  https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/

# Attempt a cross-repository blob mount
curl -i -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/?mount=sha256:abc123def456...&from=library/busybox"

curl \
 --request POST 'https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/' \
 --header "Authorization: string"