Docker Engine API (v1.37)
Download OpenAPI (fka Swagger) specification: Download
The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.
Most of the client's commands map directly to API endpoints (e.g. docker ps is GET /containers/json). The notable exception is running containers, which consists of several API calls.
Errors
The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:
{
"message": "page not found"
}
Versioning
The API is usually changed in each release, so API calls are versioned to
ensure that clients don't break. To lock to a specific version of the API,
you prefix the URL with its version, for example, call /v1.30/info to use
the v1.30 version of the /info endpoint. If the API version specified in
the URL is not supported by the daemon, a HTTP 400 Bad Request error message
is returned.
If you omit the version-prefix, the current version of the API (v1.37) is used.
For example, calling /info is the same as calling /v1.36/info. Using the
API without a version-prefix is deprecated and will be removed in a future release.
Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine.
The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons.
Authentication
Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as POST /images/(name)/push. These are sent as X-Registry-Auth header as a Base64 encoded (JSON) string with the following structure:
{
"username": "string",
"password": "string",
"email": "string",
"serveraddress": "string"
}
The serveraddress is a domain/IP without a protocol. Throughout this structure, double quotes are required.
If you have already got an identity token from the /auth endpoint, you can just pass this instead of credentials:
{
"identitytoken": "9cbaf023786cd7..."
}
List containers
Returns a list of containers. For details on the format, see the inspect endpoint.
Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .
Parameters
Return all containers. By default, only running containers are shown
Return this number of most recently created containers, including non-running ones.
Return the size of container as fields SizeRw and SizeRootFs.
Filters to process on the container list, encoded as JSON (a map[string][]string). For example, {"status": ["paused"]} will only return paused containers. Available filters:
ancestor=(<image-name>[:<tag>],<image id>, or<image@digest>)before=(<container id>or<container name>)expose=(<port>[/<proto>]|<startport-endport>/[<proto>])exited=<int>containers with exit code of<int>health=(starting|healthy|unhealthy|none)id=<ID>a container's IDisolation=(default|process|hyperv) (Windows daemon only)is-task=(true|false)label=keyorlabel="key=value"of a container labelname=<name>a container's namenetwork=(<network id>or<network name>)publish=(<port>[/<proto>]|<startport-endport>/[<proto>])since=(<container id>or<container name>)status=(created|restarting|running|removing|paused|exited|dead)volume=(<volume name>or<mount point destination>)
Responses
200 no error
400 bad parameter
500 server error
Definition
get
/containers/json200 no error
400 bad parameter
500 server error
[]
},
],
],
}
},
},
},
}
}
]
}
},
],
},
},
}
}
},
],
},
},
}
}
}
],
},
},
}
}
{}
{}
Create a container
Parameters
Assign the specified name to the container. Must match /?[a-zA-Z0-9_-]+.
Request Body
Container to create
| Hostname null |
string
The hostname to use for the container, as a valid RFC 1123 hostname. |
|
|
|
| Domainname null |
string
The domain name to use for the container. |
|
|
|
| User null |
string
The user that commands are run as inside the container. |
|
|
|
| AttachStdin null |
boolean
false
Whether to attach to |
|
|
|
| AttachStdout null |
boolean
true
Whether to attach to |
|
|
|
| AttachStderr null |
boolean
true
Whether to attach to |
|
|
|
| ExposedPorts null |
ExposedPorts
An object mapping ports to an empty object in the form:
|
|
|
|
| Tty null |
boolean
false
Attach standard streams to a TTY, including |
|
|
|
| OpenStdin null |
boolean
false
Open |
|
|
|
| StdinOnce null |
boolean
false
Close |
|
|
|
| Env null |
string
A list of environment variables to set inside the container in the form |
|
|
|
| Cmd null |
string
Command to run specified as a string or an array of strings. |
|
|
|
| Healthcheck null |
HealthConfig
A test to perform to check that the container is healthy. |
|
|
|
| ArgsEscaped null |
boolean
Command is already escaped (Windows only) |
|
|
|
| Image null |
string
The name of the image to use when creating the container |
|
|
|
| Volumes null |
Volumes
An object mapping mount point paths inside the container to empty objects. |
|
|
|
| WorkingDir null |
string
The working directory for commands to run in. |
|
|
|
| Entrypoint null |
string
The entry point for the container as a string or an array of strings. If the array consists of exactly one empty string ( |
|
|
|
| NetworkDisabled null |
boolean
Disable networking for the container. |
|
|
|
| MacAddress null |
string
MAC address of the container. |
|
|
|
| OnBuild null |
string
|
|
|
|
| Labels null |
Labels
User-defined key/value metadata. |
|
|
|
| StopSignal null |
string
"SIGTERM"
Signal to stop a container as a string or unsigned integer. |
|
|
|
| StopTimeout null |
integer
10
Timeout to stop a container in seconds. |
|
|
|
| Shell null |
string
Shell for when |
|
|
|
| HostConfig null |
HostConfig
Container configuration that depends on the host we are running on |
|
|
|
| NetworkingConfig null |
NetworkingConfig
This container's networking configuration. |
|
|
|
Responses
201 Container created successfully
400 bad parameter
404 no such container
409 conflict
500 server error
Definition
post
/containers/create{}
],
],
},
},
},
},
],
],
],
],
],
],
],
},
]
}
],
],
],
],
],
],
],
},
],
},
}
}
}
},
]
],
]
201 Container created successfully
400 bad parameter
404 no such container
409 conflict
500 server error
{}
{}
{}
{}
{}
Inspect a container
Return low-level information about a container.
Parameters
ID or name of the container
Return the size of container as fields SizeRw and SizeRootFs
Responses
200 no error
404 no such container
500 server error
Definition
get
/containers/{id}/json200 no error
404 no such container
500 server error
{}
],
},
],
],
},
},
},
],
],
],
],
],
},
},
},
],
},
}
}
},
]
}
{}
{}
List processes running inside a container
On Unix systems, this is done by running the ps command. This endpoint is not supported on Windows.
Parameters
ID or name of the container
The arguments to pass to ps. For example, aux
Responses
200 no error
404 no such container
500 server error
Definition
get
/containers/{id}/top200 no error
404 no such container
500 server error
{}
],
]
],
]
{}
{}
Get container logs
Get stdout and stderr logs from a container.
Note: This endpoint works only for containers with the json-file or journald logging driver.
Parameters
ID or name of the container
Return the logs as a stream.
This will return a 101 HTTP response with a Connection: upgrade header, then hijack the HTTP connection to send raw output. For more information about hijacking and the stream format, see the documentation for the attach endpoint.
Return logs from stdout
Return logs from stderr
Only return logs since this time, as a UNIX timestamp
Only return logs before this time, as a UNIX timestamp
Add timestamps to every log line
Only return this number of log lines from the end of the logs. Specify as an integer or all to output all log lines.
Responses
101 logs returned as a stream
200 logs returned as a string in response body
404 no such container
500 server error
Definition
get
/containers/{id}/logs101 logs returned as a stream
200 logs returned as a string in response body
404 no such container
500 server error
"string"
"string"
{}
{}
Networks
Networks are user-defined networks that containers can be attached to. See the networking documentation for more information.
Exec
Run new commands inside running containers. See the command-line reference for more information.
To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, docker exec.
Swarm
Engines can be clustered together in a swarm. See the swarm mode documentation for more information.