# Upload blob chunk


[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



`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](/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 PATCH \
  --header 'Content-Range: bytes 0-65535' \
  --header "Authorization: Bearer ${REGISTRY_TOKEN}" \
  --header 'Content-Type: application/octet-stream' \
  --data-binary @request-body \
  'https://registry-1.docker.io/v2/library%2Fubuntu/blobs/uploads/abc123'
```

Prepare request-body using the selected media type and schema.

## Parameters

### name

Location: path. Required: yes.

Repository name

```json
{
  "description": "Repository name",
  "example": "library/ubuntu",
  "in": "path",
  "name": "name",
  "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/patch/parameters/0",
  "required": true,
  "schema": {
    "type": "string"
  }
}
```

### uuid

Location: path. Required: yes.

Upload session UUID

```json
{
  "description": "Upload session UUID",
  "example": "abc123",
  "in": "path",
  "name": "uuid",
  "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/patch/parameters/1",
  "required": true,
  "schema": {
    "type": "string"
  }
}
```

### Content-Range

Location: header. Required: no.

Optional. Byte range of the chunk being sent

```json
{
  "description": "Optional. Byte range of the chunk being sent",
  "example": "bytes 0-65535",
  "in": "header",
  "name": "Content-Range",
  "pointer": "/paths/~1v2~1{name}~1blobs~1uploads~1{uuid}/patch/parameters/2",
  "required": false,
  "schema": {
    "type": "string"
  }
}
```

## Request and responses

### Request  application/octet-stream




Schema:

```json
{
  "format": "binary",
  "type": "string"
}
```




chunk-0:
```text
<binary data not shown>
```


### Response 202 

Chunk accepted and stored

No response content is declared.




Headers:

```json
{
  "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"
    }
  }
}
```



### 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.






## Complete operation contract

```json
{
  "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"
    }
  ]
}
```

## Referenced schemas