# Put image manifest


[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



`PUT /v2/{name}/manifests/{reference}`

Upload an image manifest for a given tag or digest. This operation registers a manifest in a repository, allowing it to be pulled using the specified reference.

This endpoint is typically used after all layer and config blobs have been uploaded to the registry.

The manifest must conform to the expected schema and media type. For Docker image manifest schema version 2, use:
`application/vnd.docker.distribution.manifest.v2+json`

Requires authentication via a bearer token with `push` scope for 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 PUT \
  --header "Authorization: Bearer ${REGISTRY_TOKEN}" \
  --header 'Content-Type: application/vnd.docker.distribution.manifest.v2+json' \
  --data-raw '{
  "config": {
    "digest": "sha256:123456abcdef...",
    "mediaType": "application/vnd.docker.container.image.v1+json",
    "size": 7023
  },
  "layers": [
    {
      "digest": "sha256:abcdef123456...",
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
      "size": 32654
    }
  ],
  "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
  "schemaVersion": 2
}' \
  'https://registry-1.docker.io/v2/library%2Fubuntu/manifests/<REFERENCE>'
```

## 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}~1manifests~1{reference}/put/parameters/0",
  "required": true,
  "schema": {
    "type": "string"
  }
}
```

### reference

Location: path. Required: yes.

Tag or digest to associate with the uploaded Manifest

```json
{
  "description": "Tag or digest to associate with the uploaded Manifest",
  "examples": {
    "by-digest": {
      "summary": "Digest",
      "value": "sha256:abc123def456..."
    },
    "by-tag": {
      "summary": "Tag",
      "value": "latest"
    }
  },
  "in": "path",
  "name": "reference",
  "pointer": "/paths/~1v2~1{name}~1manifests~1{reference}/put/parameters/1",
  "required": true,
  "schema": {
    "type": "string"
  }
}
```

## Request and responses

### Request  application/vnd.docker.distribution.manifest.v2+json




Schema:

```json
{
  "properties": {
    "config": {
      "properties": {
        "digest": {
          "example": "sha256:123456abcdef...",
          "type": "string"
        },
        "mediaType": {
          "example": "application/vnd.docker.container.image.v1+json",
          "type": "string"
        },
        "size": {
          "example": 7023,
          "type": "integer"
        }
      },
      "required": [
        "mediaType",
        "size",
        "digest"
      ],
      "type": "object"
    },
    "layers": {
      "items": {
        "properties": {
          "digest": {
            "example": "sha256:abcdef123456...",
            "type": "string"
          },
          "mediaType": {
            "example": "application/vnd.docker.image.rootfs.diff.tar.gzip",
            "type": "string"
          },
          "size": {
            "example": 32654,
            "type": "integer"
          }
        },
        "required": [
          "mediaType",
          "size",
          "digest"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "mediaType": {
      "example": "application/vnd.docker.distribution.manifest.v2+json",
      "type": "string"
    },
    "schemaVersion": {
      "example": 2,
      "type": "integer"
    }
  },
  "required": [
    "schemaVersion",
    "mediaType",
    "config",
    "layers"
  ],
  "type": "object"
}
```




sample-manifest:
```json
{
  "config": {
    "digest": "sha256:123456abcdef...",
    "mediaType": "application/vnd.docker.container.image.v1+json",
    "size": 7023
  },
  "layers": [
    {
      "digest": "sha256:abcdef123456...",
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
      "size": 32654
    }
  ],
  "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
  "schemaVersion": 2
}
```


### Response 201 

Manifest created successfully.

No response content is declared.




Headers:

```json
{
  "Content-Length": {
    "description": "Always zero.",
    "example": 0,
    "schema": {
      "type": "integer"
    }
  },
  "Docker-Content-Digest": {
    "description": "Digest of the stored manifest.",
    "example": "sha256:abcdef123456...",
    "schema": {
      "type": "string"
    }
  },
  "Location": {
    "description": "Canonical location of the uploaded manifest.",
    "example": "/v2/library/ubuntu/manifests/latest",
    "schema": {
      "type": "string"
    }
  }
}
```



### Response 400 

Invalid name, reference, or manifest.

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 

Repository not found.

No response content is declared.






### Response 405 

Operation not allowed.

No response content is declared.






### Response 429 

Too many requests.

No response content is declared.






## Complete operation contract

```json
{
  "description": "Upload an image manifest for a given tag or digest. This operation registers a manifest in a repository, allowing it to be pulled using the specified reference.\n\nThis endpoint is typically used after all layer and config blobs have been uploaded to the registry.\n\nThe manifest must conform to the expected schema and media type. For Docker image manifest schema version 2, use:\n`application/vnd.docker.distribution.manifest.v2+json`\n\nRequires authentication via a bearer token with `push` scope for the target repository.\n",
  "operationId": "PutImageManifest",
  "parameters": [
    {
      "description": "Name of the target Repository",
      "example": "library/ubuntu",
      "in": "path",
      "name": "name",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Tag or digest to associate with the uploaded Manifest",
      "examples": {
        "by-digest": {
          "summary": "Digest",
          "value": "sha256:abc123def456..."
        },
        "by-tag": {
          "summary": "Tag",
          "value": "latest"
        }
      },
      "in": "path",
      "name": "reference",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/vnd.docker.distribution.manifest.v2+json": {
        "examples": {
          "sample-manifest": {
            "summary": "Sample Docker image manifest (schema v2)",
            "value": {
              "config": {
                "digest": "sha256:123456abcdef...",
                "mediaType": "application/vnd.docker.container.image.v1+json",
                "size": 7023
              },
              "layers": [
                {
                  "digest": "sha256:abcdef123456...",
                  "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
                  "size": 32654
                }
              ],
              "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
              "schemaVersion": 2
            }
          }
        },
        "schema": {
          "properties": {
            "config": {
              "properties": {
                "digest": {
                  "example": "sha256:123456abcdef...",
                  "type": "string"
                },
                "mediaType": {
                  "example": "application/vnd.docker.container.image.v1+json",
                  "type": "string"
                },
                "size": {
                  "example": 7023,
                  "type": "integer"
                }
              },
              "required": [
                "mediaType",
                "size",
                "digest"
              ],
              "type": "object"
            },
            "layers": {
              "items": {
                "properties": {
                  "digest": {
                    "example": "sha256:abcdef123456...",
                    "type": "string"
                  },
                  "mediaType": {
                    "example": "application/vnd.docker.image.rootfs.diff.tar.gzip",
                    "type": "string"
                  },
                  "size": {
                    "example": 32654,
                    "type": "integer"
                  }
                },
                "required": [
                  "mediaType",
                  "size",
                  "digest"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "mediaType": {
              "example": "application/vnd.docker.distribution.manifest.v2+json",
              "type": "string"
            },
            "schemaVersion": {
              "example": 2,
              "type": "integer"
            }
          },
          "required": [
            "schemaVersion",
            "mediaType",
            "config",
            "layers"
          ],
          "type": "object"
        }
      }
    },
    "required": true
  },
  "responses": {
    "201": {
      "description": "Manifest created successfully.",
      "headers": {
        "Content-Length": {
          "description": "Always zero.",
          "example": 0,
          "schema": {
            "type": "integer"
          }
        },
        "Docker-Content-Digest": {
          "description": "Digest of the stored manifest.",
          "example": "sha256:abcdef123456...",
          "schema": {
            "type": "string"
          }
        },
        "Location": {
          "description": "Canonical location of the uploaded manifest.",
          "example": "/v2/library/ubuntu/manifests/latest",
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "400": {
      "description": "Invalid name, reference, or manifest."
    },
    "401": {
      "description": "Authentication required."
    },
    "403": {
      "description": "Access denied."
    },
    "404": {
      "description": "Repository not found."
    },
    "405": {
      "description": "Operation not allowed."
    },
    "429": {
      "description": "Too many requests."
    }
  },
  "summary": "Put image manifest",
  "tags": [
    "Manifests"
  ],
  "x-codeSamples": [
    {
      "label": "cURL",
      "lang": "Bash",
      "source": "# PUT a manifest (tag = latest)\ncurl -X PUT \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/vnd.docker.distribution.manifest.v2+json\" \\\n  --data-binary @manifest.json \\\n  https://registry-1.docker.io/v2/library/ubuntu/manifests/latest\n"
    }
  ]
}
```

## Referenced schemas