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

Upload blob chunk

PATCH/v2/{name}/blobs/uploads/{uuid}

Upload a chunk of a blob to an active upload session.

Use this method for chunked uploads, especially for large blobs or when resuming interrupted uploads.

The client sends binary data using PATCH, optionally including a Content-Range header.

After each chunk is accepted, the registry returns a 202 Accepted response with:

  • Range: current byte range stored
  • Docker-Upload-UUID: identifier for the upload session
  • Location: URL to continue the upload or finalize with PUT

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

Repository name

Type: string

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

uuid path Required

Upload session UUID

Type: string

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

Content-Range header

Optional. Byte range of the chunk being sent

Type: string

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

Request and responses

Request

application/octet-stream

Type: string

All schema constraints and annotations
{
  "format": "binary",
  "type": "string"
}

chunk-0

<binary data not shown>

Response 202

Chunk accepted and stored

No response content is declared.

Headers

Docker-Upload-UUID

Upload session UUID

{
  "description": "Upload session UUID",
  "example": "abc123",
  "schema": {
    "type": "string"
  }
}
Location

URL to continue or finalize the upload

{
  "description": "URL to continue or finalize the upload",
  "example": "/v2/library/ubuntu/blobs/uploads/abc123",
  "schema": {
    "type": "string"
  }
}
Range

Byte range uploaded so far (inclusive)

{
  "description": "Byte range uploaded so far (inclusive)",
  "example": "0-65535",
  "schema": {
    "type": "string"
  }
}

Response 400

Malformed content or range

No response content is declared.

Response 401

Authentication required

No response content is declared.

Response 403

Access denied

No response content is declared.

Response 404

Upload session not found

No response content is declared.

Response 416

Range error (e.g., chunk out of order)

No response content is declared.

Response 429

Too many requests

No response content is declared.

Referenced schemas

Complete operation contract
{
  "description": "Upload a chunk of a blob to an active upload session.\n\nUse this method for **chunked uploads**, especially for large blobs or when resuming interrupted uploads.\n\nThe client sends binary data using `PATCH`, optionally including a `Content-Range` header.\n\nAfter each chunk is accepted, the registry returns a `202 Accepted` response with:\n- `Range`: current byte range stored\n- `Docker-Upload-UUID`: identifier for the upload session\n- `Location`: URL to continue the upload or finalize with `PUT`\n",
  "operationId": "UploadBlobChunk",
  "parameters": [
    {
      "description": "Repository name",
      "example": "library/ubuntu",
      "in": "path",
      "name": "name",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Upload session UUID",
      "example": "abc123",
      "in": "path",
      "name": "uuid",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Optional. Byte range of the chunk being sent",
      "example": "bytes 0-65535",
      "in": "header",
      "name": "Content-Range",
      "required": false,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/octet-stream": {
        "examples": {
          "chunk-0": {
            "summary": "Upload chunk 0 of a blob",
            "value": "\u003cbinary data not shown\u003e"
          }
        },
        "schema": {
          "format": "binary",
          "type": "string"
        }
      }
    },
    "required": true
  },
  "responses": {
    "202": {
      "description": "Chunk accepted and stored",
      "headers": {
        "Docker-Upload-UUID": {
          "description": "Upload session UUID",
          "example": "abc123",
          "schema": {
            "type": "string"
          }
        },
        "Location": {
          "description": "URL to continue or finalize the upload",
          "example": "/v2/library/ubuntu/blobs/uploads/abc123",
          "schema": {
            "type": "string"
          }
        },
        "Range": {
          "description": "Byte range uploaded so far (inclusive)",
          "example": "0-65535",
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "400": {
      "description": "Malformed content or range"
    },
    "401": {
      "description": "Authentication required"
    },
    "403": {
      "description": "Access denied"
    },
    "404": {
      "description": "Upload session not found"
    },
    "416": {
      "description": "Range error (e.g., chunk out of order)"
    },
    "429": {
      "description": "Too many requests"
    }
  },
  "summary": "Upload blob chunk",
  "tags": [
    "Blobs"
  ],
  "x-codeSamples": [
    {
      "label": "cURL",
      "lang": "Bash",
      "source": "# PATCH – upload a chunk (first 64 KiB)\ncurl -X PATCH \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/octet-stream\" \\\n  --data-binary @chunk-0.bin \\\n  \"https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/abc123\"\n"
    }
  ]
}