# Initiate blob upload or attempt cross-repository blob mount [API catalog](/reference/api/) · [Registry overview](/reference/api/registry/latest/) · [Product manual](https://docs.docker.com/docker-hub/repos/) · [OpenAPI specification](/reference/api/registry/latest.yaml) API version: 2 `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](/reference/api/registry/latest/#authentication) Server: `https://registry-1.docker.io` Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement. ```json [ { "registryToken": [] } ] ``` ## Example request Replace placeholders and provide the required credentials or request body. ```console curl \ --request POST \ --header "Authorization: Bearer ${REGISTRY_TOKEN}" \ 'https://registry-1.docker.io/v2/library%2Fubuntu/blobs/uploads/?mount=sha256%3Aabc123def456...&from=library%2Fbusybox' ``` ## Parameters ### name Location: path. Required: yes. Name of the target repository ```json { "description": "Name of the target repository", "example": "library/ubuntu", "in": "path", "name": "name", "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1/post/parameters/0", "required": true, "schema": { "type": "string" } } ``` ### mount Location: query. Required: no. Digest of the blob to mount from another repository ```json { "description": "Digest of the blob to mount from another repository", "example": "sha256:abc123def456...", "in": "query", "name": "mount", "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1/post/parameters/1", "required": false, "schema": { "type": "string" } } ``` ### from Location: query. Required: no. Source repository to mount the blob from ```json { "description": "Source repository to mount the blob from", "example": "library/busybox", "in": "query", "name": "from", "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1/post/parameters/2", "required": false, "schema": { "type": "string" } } ``` ## Request and responses ### Response 201 Blob successfully mounted from another repository. No response content is declared. Headers: ```json { "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" } } } ``` ### Response 202 Upload initiated successfully (fallback if mount fails). No response content is declared. Headers: ```json { "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" } } } ``` ### 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. ## Complete operation contract ```json { "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" } ] } ``` ## Referenced schemas