Share feedback
Answers are generated based on the documentation.
Product manualDownload OpenAPI specificationMarkdown

Initiate blob upload or attempt cross-repository blob mount

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.

Connection and access

API connection and authentication guidance

https://registry-1.docker.io — Docker Hub registry API

Use one of these alternatives. Requirements within an alternative apply together.

  • registryToken

Parameters

name path Required

Name of the target repository

Type: string

All schema constraints and annotations
{
  "type": "string"
}

mount query

Digest of the blob to mount from another repository

Type: string

All schema constraints and annotations
{
  "type": "string"
}

from query

Source repository to mount the blob from

Type: string

All schema constraints and annotations
{
  "type": "string"
}

Request and responses

Response 201

Blob successfully mounted from another repository.

No response content is declared.

Headers

Content-Length

Always zero

{
  "description": "Always zero",
  "example": 0,
  "schema": {
    "type": "integer"
  }
}
Docker-Content-Digest

Canonical digest of the mounted blob

{
  "description": "Canonical digest of the mounted blob",
  "example": "sha256:abc123...",
  "schema": {
    "type": "string"
  }
}
Location

URL where the mounted blob is accessible

{
  "description": "URL where the mounted blob is accessible",
  "example": "/v2/library/ubuntu/blobs/sha256:abc123...",
  "schema": {
    "type": "string"
  }
}

Response 202

Upload initiated successfully (fallback if mount fails).

No response content is declared.

Headers

Content-Length

Always zero

{
  "description": "Always zero",
  "example": 0,
  "schema": {
    "type": "integer"
  }
}
Docker-Upload-UUID

Server-generated UUID for the upload session

{
  "description": "Server-generated UUID for the upload session",
  "example": "abc123",
  "schema": {
    "type": "string"
  }
}
Location

Upload location URL for `PATCH` or `PUT` requests

{
  "description": "Upload location URL for `PATCH` or `PUT` requests",
  "example": "/v2/library/ubuntu/blobs/uploads/abc123",
  "schema": {
    "type": "string"
  }
}
Range

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

{
  "description": "Current upload byte range (typically `0-0` at init)",
  "example": "0-0",
  "schema": {
    "type": "string"
  }
}

Response 401

Authentication required.

No response content is declared.

Response 403

Access denied.

No response content is declared.

Response 404

Repository not found.

No response content is declared.

Response 429

Too many requests.

No response content is declared.

Referenced schemas

Complete operation contract
{
  "description": "Initiate an upload session for a blob (layer or config) in a repository.\n\nThis 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).\n\nInstead 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.\n\nIf successful, the registry responds with `201 Created` and the blob is reused without re-upload.\n\nIf the mount fails, the upload proceeds as usual and returns a `202 Accepted`.\n\nYou must authenticate with `push` access to the target repository.\n",
  "operationId": "InitiateBlobUpload",
  "parameters": [
    {
      "description": "Name of the target repository",
      "example": "library/ubuntu",
      "in": "path",
      "name": "name",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Digest of the blob to mount from another repository",
      "example": "sha256:abc123def456...",
      "in": "query",
      "name": "mount",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Source repository to mount the blob from",
      "example": "library/busybox",
      "in": "query",
      "name": "from",
      "required": false,
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "201": {
      "description": "Blob successfully mounted from another repository.",
      "headers": {
        "Content-Length": {
          "description": "Always zero",
          "example": 0,
          "schema": {
            "type": "integer"
          }
        },
        "Docker-Content-Digest": {
          "description": "Canonical digest of the mounted blob",
          "example": "sha256:abc123...",
          "schema": {
            "type": "string"
          }
        },
        "Location": {
          "description": "URL where the mounted blob is accessible",
          "example": "/v2/library/ubuntu/blobs/sha256:abc123...",
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "202": {
      "description": "Upload initiated successfully (fallback if mount fails).",
      "headers": {
        "Content-Length": {
          "description": "Always zero",
          "example": 0,
          "schema": {
            "type": "integer"
          }
        },
        "Docker-Upload-UUID": {
          "description": "Server-generated UUID for the upload session",
          "example": "abc123",
          "schema": {
            "type": "string"
          }
        },
        "Location": {
          "description": "Upload location URL for `PATCH` or `PUT` requests",
          "example": "/v2/library/ubuntu/blobs/uploads/abc123",
          "schema": {
            "type": "string"
          }
        },
        "Range": {
          "description": "Current upload byte range (typically `0-0` at init)",
          "example": "0-0",
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required."
    },
    "403": {
      "description": "Access denied."
    },
    "404": {
      "description": "Repository not found."
    },
    "429": {
      "description": "Too many requests."
    }
  },
  "summary": "Initiate blob upload or attempt cross-repository blob mount",
  "tags": [
    "Blobs"
  ],
  "x-codeSamples": [
    {
      "label": "cURL (Initiate Standard Upload)",
      "lang": "Bash",
      "source": "# Initiate a standard blob upload session\ncurl -i -X POST \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/\n"
    },
    {
      "label": "cURL (Cross-Repository Blob Mount)",
      "lang": "Bash",
      "source": "# Attempt a cross-repository blob mount\ncurl -i -X POST \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  \"https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/?mount=sha256:abc123def456...\u0026from=library/busybox\"\n"
    }
  ]
}