Docker Image API
The Image API from Docker — 15 operation(s) for image.
OpenAPI Specification
swagger: '2.0'
info:
title: Docker Engine Config Image API
version: '1.54'
x-logo:
url: https://docs.docker.com/assets/images/logo-docker-main.png
description: "The Engine API is an HTTP API served by Docker Engine. It is the API the\nDocker client uses to communicate with the Engine, so everything the Docker\nclient can do can be done with the API.\n\nMost of the client's commands map directly to API endpoints (e.g. `docker ps`\nis `GET /containers/json`). The notable exception is running containers,\nwhich consists of several API calls.\n\n# Errors\n\nThe API uses standard HTTP status codes to indicate the success or failure\nof the API call. The body of the response will be JSON in the following\nformat:\n\n```\n{\n \"message\": \"page not found\"\n}\n```\n\n# Versioning\n\nThe API is usually changed in each release, so API calls are versioned to\nensure that clients don't break. To lock to a specific version of the API,\nyou prefix the URL with its version, for example, call `/v1.30/info` to use\nthe v1.30 version of the `/info` endpoint. If the API version specified in\nthe URL is not supported by the daemon, a HTTP `400 Bad Request` error message\nis returned.\n\nIf you omit the version-prefix, the current version of the API (v1.50) is used.\nFor example, calling `/info` is the same as calling `/v1.52/info`. Using the\nAPI without a version-prefix is deprecated and will be removed in a future release.\n\nEngine releases in the near future should support this version of the API,\nso your client will continue to work even if it is talking to a newer Engine.\n\nThe API uses an open schema model, which means the server may add extra properties\nto responses. Likewise, the server will ignore any extra query parameters and\nrequest body properties. When you write clients, you need to ignore additional\nproperties in responses to ensure they do not break when talking to newer\ndaemons.\n\n\n# Authentication\n\nAuthentication for registries is handled client side. The client has to send\nauthentication details to various endpoints that need to communicate with\nregistries, such as `POST /images/(name)/push`. These are sent as\n`X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5)\n(JSON) string with the following structure:\n\n```\n{\n \"username\": \"string\",\n \"password\": \"string\",\n \"serveraddress\": \"string\"\n}\n```\n\nThe `serveraddress` is a domain/IP without a protocol. Throughout this\nstructure, double quotes are required.\n\nIf you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth),\nyou can just pass this instead of credentials:\n\n```\n{\n \"identitytoken\": \"9cbaf023786cd7...\"\n}\n```\n"
basePath: /v1.54
schemes:
- http
- https
consumes:
- application/json
- text/plain
produces:
- application/json
- text/plain
tags:
- name: Image
x-displayName: Images
paths:
/images/json:
get:
summary: List Images
description: Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.
operationId: ImageList
produces:
- application/json
responses:
200:
description: Summary image data for the images matching the query
schema:
type: array
items:
$ref: '#/definitions/ImageSummary'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: all
in: query
description: Show all images. Only images from a final layer (no children) are shown by default.
type: boolean
default: false
- name: filters
in: query
description: 'A JSON encoded value of the filters (a `map[string][]string`) to
process on the images list.
Available filters:
- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `until=<timestamp>`
'
type: string
- name: shared-size
in: query
description: Compute and show shared size as a `SharedSize` field on each image.
type: boolean
default: false
- name: digests
in: query
description: Show digest information as a `RepoDigests` field on each image.
type: boolean
default: false
- name: manifests
in: query
description: Include `Manifests` in the image summary.
type: boolean
default: false
- name: identity
in: query
description: Include `Identity` in each manifest summary. Requires `manifests=1`.
type: boolean
default: false
tags:
- Image
/build:
post:
summary: Build an image
description: 'Build an image from a tar archive with a `Dockerfile` in it.
The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive''s root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).
The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.
The build is canceled if the client drops the connection by quitting or being killed.
'
operationId: ImageBuild
consumes:
- application/octet-stream
produces:
- application/json
parameters:
- name: inputStream
in: body
description: 'A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.'
schema:
type: string
format: binary
- name: dockerfile
in: query
description: Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.
type: string
default: Dockerfile
- name: t
in: query
description: A name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.
type: string
- name: extrahosts
in: query
description: Extra hosts to add to /etc/hosts
type: string
- name: remote
in: query
description: A Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.
type: string
- name: q
in: query
description: Suppress verbose build output.
type: boolean
default: false
- name: nocache
in: query
description: Do not use the cache when building the image.
type: boolean
default: false
- name: cachefrom
in: query
description: JSON array of images used for build cache resolution.
type: string
- name: pull
in: query
description: Attempt to pull the image even if an older image exists locally.
type: string
- name: rm
in: query
description: Remove intermediate containers after a successful build.
type: boolean
default: true
- name: forcerm
in: query
description: Always remove intermediate containers, even upon failure.
type: boolean
default: false
- name: memory
in: query
description: Set memory limit for build.
type: integer
- name: memswap
in: query
description: Total memory (memory + swap). Set as `-1` to disable swap.
type: integer
- name: cpushares
in: query
description: CPU shares (relative weight).
type: integer
- name: cpusetcpus
in: query
description: CPUs in which to allow execution (e.g., `0-3`, `0,1`).
type: string
- name: cpuperiod
in: query
description: The length of a CPU period in microseconds.
type: integer
- name: cpuquota
in: query
description: Microseconds of CPU time that the container can get in a CPU period.
type: integer
- name: buildargs
in: query
description: 'JSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.
For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.
[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg)
'
type: string
- name: shmsize
in: query
description: Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.
type: integer
- name: squash
in: query
description: Squash the resulting images layers into a single layer. *(Experimental release only.)*
type: boolean
- name: labels
in: query
description: Arbitrary key/value labels to set on the image, as a JSON map of string pairs.
type: string
- name: networkmode
in: query
description: 'Sets the networking mode for the run commands during build. Supported
standard values are: `bridge`, `host`, `none`, and `container:<name|id>`.
Any other value is taken as a custom network''s name or ID to which this
container should connect to.
'
type: string
- name: Content-type
in: header
type: string
enum:
- application/x-tar
default: application/x-tar
- name: X-Registry-Config
in: header
description: "This is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.\n\nThe key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:\n\n```\n{\n \"docker.example.com\": {\n \"username\": \"janedoe\",\n \"password\": \"hunter2\"\n },\n \"https://index.docker.io/v1/\": {\n \"username\": \"mobydock\",\n \"password\": \"conta1n3rize14\"\n }\n}\n```\n\nOnly the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API.\n"
type: string
- name: platform
in: query
description: Platform in the format os[/arch[/variant]]
type: string
default: ''
- name: target
in: query
description: Target build stage
type: string
default: ''
- name: outputs
in: query
description: 'BuildKit output configuration in the format of a stringified JSON array of objects.
Each object must have two top-level properties: `Type` and `Attrs`.
The `Type` property must be set to ''moby''.
The `Attrs` property is a map of attributes for the BuildKit output configuration.
See https://docs.docker.com/build/exporters/oci-docker/ for more information.
Example:
```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```
'
type: string
default: ''
- name: version
in: query
type: string
default: '1'
enum:
- '1'
- '2'
description: 'Version of the builder backend to use.
- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)
'
responses:
200:
description: no error
400:
description: Bad parameter
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
tags:
- Image
/build/prune:
post:
summary: Delete builder cache
produces:
- application/json
operationId: BuildPrune
parameters:
- name: reserved-space
in: query
description: Amount of disk space in bytes to keep for cache
type: integer
format: int64
- name: max-used-space
in: query
description: Maximum amount of disk space allowed to keep for cache
type: integer
format: int64
- name: min-free-space
in: query
description: Target amount of free disk space after pruning
type: integer
format: int64
- name: all
in: query
type: boolean
description: Remove all types of build cache
- name: filters
in: query
type: string
description: 'A JSON encoded value of the filters (a `map[string][]string`) to
process on the list of build cache objects.
Available filters:
- `until=<timestamp>` remove cache older than `<timestamp>`. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon''s local time.
- `id=<id>`
- `parent=<id>`
- `type=<string>`
- `description=<string>`
- `inuse`
- `shared`
- `private`
'
responses:
200:
description: No error
schema:
type: object
title: BuildPruneResponse
properties:
CachesDeleted:
type: array
items:
description: ID of build cache object
type: string
SpaceReclaimed:
description: Disk space reclaimed in bytes
type: integer
format: int64
500:
description: Server error
schema:
$ref: '#/definitions/ErrorResponse'
tags:
- Image
/images/create:
post:
summary: Create an image
description: Pull or import an image.
operationId: ImageCreate
consumes:
- text/plain
- application/octet-stream
produces:
- application/json
responses:
200:
description: no error
404:
description: repository does not exist or no read access
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: fromImage
in: query
description: 'Name of the image to pull. If the name includes a tag or digest, specific behavior applies:
- If only `fromImage` includes a tag, that tag is used.
- If both `fromImage` and `tag` are provided, `tag` takes precedence.
- If `fromImage` includes a digest, the image is pulled by digest, and `tag` is ignored.
- If neither a tag nor digest is specified, all tags are pulled.
'
type: string
- name: fromSrc
in: query
description: Source to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.
type: string
- name: repo
in: query
description: Repository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.
type: string
- name: tag
in: query
description: Tag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.
type: string
- name: message
in: query
description: Set commit message for imported image.
type: string
- name: inputImage
in: body
description: Image content if the value `-` has been specified in fromSrc query parameter
schema:
type: string
required: false
- name: X-Registry-Auth
in: header
description: 'A base64url-encoded auth configuration.
Refer to the [authentication section](#section/Authentication) for
details.
'
type: string
- name: changes
in: query
description: 'Apply `Dockerfile` instructions to the image that is created,
for example: `changes=ENV DEBUG=true`.
Note that `ENV DEBUG=true` should be URI component encoded.
Supported `Dockerfile` instructions:
`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR`
'
type: array
items:
type: string
- name: platform
in: query
description: 'Platform in the format os[/arch[/variant]].
When used in combination with the `fromImage` option, the daemon checks
if the given image is present in the local image cache with the given
OS and Architecture, and otherwise attempts to pull the image. If the
option is not set, the host''s native OS and Architecture are used.
If the given image does not exist in the local image cache, the daemon
attempts to pull the image with the host''s native OS and Architecture.
If the given image does exists in the local image cache, but its OS or
architecture does not match, a warning is produced.
When used with the `fromSrc` option to import an image from an archive,
this option sets the platform information for the imported image. If
the option is not set, the host''s native OS and Architecture are used
for the imported image.
'
type: string
default: ''
tags:
- Image
/images/{name}/json:
get:
summary: Inspect an image
description: Return low-level information about an image.
operationId: ImageInspect
produces:
- application/json
responses:
200:
description: No error
schema:
$ref: '#/definitions/ImageInspect'
404:
description: No such image
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such image: someimage (tag: latest)'
500:
description: Server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: name
in: path
description: Image name or id
type: string
required: true
- name: manifests
in: query
description: 'Include Manifests in the image summary.
The `manifests` and `platform` options are mutually exclusive, and
an error is produced if both are set.'
type: boolean
default: false
required: false
- name: platform
type: string
in: query
description: 'JSON-encoded OCI platform to select the platform-variant.
If omitted, it defaults to any locally available platform,
prioritizing the daemon''s host platform.
If the daemon provides a multi-platform image store, this selects
the platform-variant to show inspect. If the image is
a single-platform image, or if the multi-platform image does not
provide a variant matching the given platform, an error is returned.
The `platform` and `manifests` options are mutually exclusive, and
an error is produced if both are set.
Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}`'
tags:
- Image
/images/{name}/history:
get:
summary: Get the history of an image
description: Return parent layers of an image.
operationId: ImageHistory
produces:
- application/json
responses:
200:
description: List of image layers
schema:
type: array
items:
$ref: '#/definitions/ImageHistoryResponseItem'
examples:
application/json:
- Id: 3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710
Created: 1398108230
CreatedBy: '/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /'
Tags:
- ubuntu:lucid
- ubuntu:10.04
Size: 182964289
Comment: ''
- Id: 6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8
Created: 1398108222
CreatedBy: '/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/'
Tags: []
Size: 0
Comment: ''
- Id: 511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158
Created: 1371157430
CreatedBy: ''
Tags:
- scratch12:latest
- scratch:latest
Size: 0
Comment: Imported from -
404:
description: No such image
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: Server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: name
in: path
description: Image name or ID
type: string
required: true
- name: platform
type: string
in: query
description: 'JSON-encoded OCI platform to select the platform-variant.
If omitted, it defaults to any locally available platform,
prioritizing the daemon''s host platform.
If the daemon provides a multi-platform image store, this selects
the platform-variant to show the history for. If the image is
a single-platform image, or if the multi-platform image does not
provide a variant matching the given platform, an error is returned.
Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}`
'
tags:
- Image
/images/{name}/push:
post:
summary: Push an image
description: 'Push an image to a registry.
If you wish to push an image on to a private registry, that image must
already have a tag which references the registry. For example,
`registry.example.com/myimage:latest`.
The push is cancelled if the HTTP connection is closed.
'
operationId: ImagePush
consumes:
- application/octet-stream
responses:
200:
description: No error
404:
description: No such image
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: Server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: name
in: path
description: 'Name of the image to push. For example, `registry.example.com/myimage`.
The image must be present in the local image store with the same name.
The name should be provided without tag; if a tag is provided, it
is ignored. For example, `registry.example.com/myimage:latest` is
considered equivalent to `registry.example.com/myimage`.
Use the `tag` parameter to specify the tag to push.
'
type: string
required: true
- name: tag
in: query
description: 'Tag of the image to push. For example, `latest`. If no tag is provided,
all tags of the given image that are present in the local image store
are pushed.
'
type: string
- name: platform
type: string
in: query
description: 'JSON-encoded OCI platform to select the platform-variant to push.
If not provided, all available variants will attempt to be pushed.
If the daemon provides a multi-platform image store, this selects
the platform-variant to push to the registry. If the image is
a single-platform image, or if the multi-platform image does not
provide a variant matching the given platform, an error is returned.
Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}`
'
- name: X-Registry-Auth
in: header
description: 'A base64url-encoded auth configuration.
Refer to the [authentication section](#section/Authentication) for
details.
'
type: string
required: true
tags:
- Image
/images/{name}/tag:
post:
summary: Tag an image
description: 'Create a tag that refers to a source image.
This creates an additional reference (tag) to the source image. The tag
can include a different repository name and/or tag. If the repository
or tag already exists, it will be overwritten.
'
operationId: ImageTag
responses:
201:
description: No error
400:
description: Bad parameter
schema:
$ref: '#/definitions/ErrorResponse'
404:
description: No such image
schema:
$ref: '#/definitions/ErrorResponse'
409:
description: Conflict
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: Server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: name
in: path
description: Image name or ID to tag.
type: string
required: true
- name: repo
in: query
description: The repository to tag in. For example, `someuser/someimage`.
type: string
- name: tag
in: query
description: The name of the new tag.
type: string
tags:
- Image
/images/{name}:
delete:
summary: Remove an image
description: 'Remove an image, along with any untagged parent images that were
referenced by that image.
Images can''t be removed if they have descendant images, are being
used by a running container or are being used by a build.
'
operationId: ImageDelete
produces:
- application/json
responses:
200:
description: The image was deleted successfully
schema:
type: array
items:
$ref: '#/definitions/ImageDeleteResponseItem'
examples:
application/json:
- Untagged: 3e2f21a89f
- Deleted: 3e2f21a89f
- Deleted: 53b4f83ac9
404:
description: No such image
schema:
$ref: '#/definitions/ErrorResponse'
409:
description: Conflict
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: Server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: name
in: path
description: Image name or ID
type: string
required: true
- name: force
in: query
description: Remove the image even if it is being used by stopped containers or has other tags
type: boolean
default: false
- name: noprune
in: query
description: Do not delete untagged parent images
type: boolean
default: false
- name: platforms
in: query
description: 'Select platform-specific content to delete.
Multiple values are accepted.
Each platform is a OCI platform encoded as a JSON string.
'
type: array
items:
type: string
tags:
- Image
/images/search:
get:
summary: Search images
description: Search for an image on Docker Hub.
operationId: ImageSearch
produces:
- application/json
responses:
200:
description: No error
schema:
type: array
items:
type: object
title: ImageSearchResponseItem
properties:
description:
type: string
is_official:
type: boolean
is_automated:
description: 'Whether this repository has automated builds enabled.
<p><br /></p>
> **Deprecated**: This field is deprecated and will always be "false".
'
type: boolean
example: false
name:
type: string
star_count:
type: integer
examples:
application/json:
- description: A minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size!
is_official: true
is_automated: false
name: alpine
star_count: 10093
- description: Busybox base image.
is_official: true
is_automated: false
name: Busybox base image.
star_count: 3037
- description: The PostgreSQL object-relational database system provides reliability and data integrity.
is_official: true
is_automated: false
name: postgres
star_count: 12408
500:
description: Server error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: term
in: query
description: Term to search
type: string
required: true
- name: limit
in: query
description: Maximum number of results to return
type: integer
- name: filters
in: query
description: 'A JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:
- `is-official=(true|false)`
- `stars=<number>` Matches images that has at least ''number'' stars.
'
type: string
tags:
- Image
/images/prune:
post:
summary: Delete unused images
produces:
- application/json
operationId: ImagePrune
parameters:
- name: filters
in: query
description: "Filters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:\n\n- `dangling=<boolean>` When set to `true` (or `1`), prune only\n unused *and* untagged images. When set to `false`\n (or `0`), all unused images are pruned.\n- `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.\n- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels.\n"
type: string
responses:
200:
# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/docker/refs/heads/main/openapi/docker-image-api-openapi.yml