Docker Task API
A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.
OpenAPI Specification
swagger: '2.0'
info:
title: Docker Engine Config Task 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: Task
x-displayName: Tasks
description: 'A task is a container running on a swarm. It is the atomic scheduling unit
of swarm. Swarm mode must be enabled for these endpoints to work.
'
paths:
/tasks:
get:
summary: List tasks
operationId: TaskList
produces:
- application/json
responses:
200:
description: no error
schema:
type: array
items:
$ref: '#/definitions/Task'
example:
- ID: 0kzzo1i0y4jz6027t0k7aezc7
Version:
Index: 71
CreatedAt: '2016-06-07T21:07:31.171892745Z'
UpdatedAt: '2016-06-07T21:07:31.376370513Z'
Spec:
ContainerSpec:
Image: redis
Resources:
Limits: {}
Reservations: {}
RestartPolicy:
Condition: any
MaxAttempts: 0
Placement: {}
ServiceID: 9mnpnzenvg8p8tdbtq4wvbkcz
Slot: 1
NodeID: 60gvrl6tm78dmak4yl7srz94v
Status:
Timestamp: '2016-06-07T21:07:31.290032978Z'
State: running
Message: started
ContainerStatus:
ContainerID: e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035
PID: 677
DesiredState: running
NetworksAttachments:
- Network:
ID: 4qvuz4ko70xaltuqbt8956gd1
Version:
Index: 18
CreatedAt: '2016-06-07T20:31:11.912919752Z'
UpdatedAt: '2016-06-07T21:07:29.955277358Z'
Spec:
Name: ingress
Labels:
com.docker.swarm.internal: 'true'
DriverConfiguration: {}
IPAMOptions:
Driver: {}
Configs:
- Subnet: 10.255.0.0/16
Gateway: 10.255.0.1
DriverState:
Name: overlay
Options:
com.docker.network.driver.overlay.vxlanid_list: '256'
IPAMOptions:
Driver:
Name: default
Configs:
- Subnet: 10.255.0.0/16
Gateway: 10.255.0.1
Addresses:
- 10.255.0.10/16
- ID: 1yljwbmlr8er2waf8orvqpwms
Version:
Index: 30
CreatedAt: '2016-06-07T21:07:30.019104782Z'
UpdatedAt: '2016-06-07T21:07:30.231958098Z'
Name: hopeful_cori
Spec:
ContainerSpec:
Image: redis
Resources:
Limits: {}
Reservations: {}
RestartPolicy:
Condition: any
MaxAttempts: 0
Placement: {}
ServiceID: 9mnpnzenvg8p8tdbtq4wvbkcz
Slot: 1
NodeID: 60gvrl6tm78dmak4yl7srz94v
Status:
Timestamp: '2016-06-07T21:07:30.202183143Z'
State: shutdown
Message: shutdown
ContainerStatus:
ContainerID: 1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213
DesiredState: shutdown
NetworksAttachments:
- Network:
ID: 4qvuz4ko70xaltuqbt8956gd1
Version:
Index: 18
CreatedAt: '2016-06-07T20:31:11.912919752Z'
UpdatedAt: '2016-06-07T21:07:29.955277358Z'
Spec:
Name: ingress
Labels:
com.docker.swarm.internal: 'true'
DriverConfiguration: {}
IPAMOptions:
Driver: {}
Configs:
- Subnet: 10.255.0.0/16
Gateway: 10.255.0.1
DriverState:
Name: overlay
Options:
com.docker.network.driver.overlay.vxlanid_list: '256'
IPAMOptions:
Driver:
Name: default
Configs:
- Subnet: 10.255.0.0/16
Gateway: 10.255.0.1
Addresses:
- 10.255.0.5/16
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
503:
description: node is not part of a swarm
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: filters
in: query
type: string
description: 'A JSON encoded value of the filters (a `map[string][]string`) to
process on the tasks list.
Available filters:
- `desired-state=(running | shutdown | accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>`
'
tags:
- Task
/tasks/{id}:
get:
summary: Inspect a task
operationId: TaskInspect
produces:
- application/json
responses:
200:
description: no error
schema:
$ref: '#/definitions/Task'
404:
description: no such task
schema:
$ref: '#/definitions/ErrorResponse'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
503:
description: node is not part of a swarm
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
description: ID of the task
required: true
type: string
tags:
- Task
/tasks/{id}/logs:
get:
summary: Get task logs
description: 'Get `stdout` and `stderr` logs from a task.
See also [`/containers/{id}/logs`](#operation/ContainerLogs).
**Note**: This endpoint works only for services with the `local`,
`json-file` or `journald` logging drivers.
'
operationId: TaskLogs
produces:
- application/vnd.docker.raw-stream
- application/vnd.docker.multiplexed-stream
responses:
200:
description: logs returned as a stream in response body
schema:
type: string
format: binary
404:
description: no such task
schema:
$ref: '#/definitions/ErrorResponse'
examples:
application/json:
message: 'No such task: c2ada9df5af8'
500:
description: server error
schema:
$ref: '#/definitions/ErrorResponse'
503:
description: node is not part of a swarm
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
- name: id
in: path
required: true
description: ID of the task
type: string
- name: details
in: query
description: Show task context and extra details provided to logs.
type: boolean
default: false
- name: follow
in: query
description: Keep connection after returning logs.
type: boolean
default: false
- name: stdout
in: query
description: Return logs from `stdout`
type: boolean
default: false
- name: stderr
in: query
description: Return logs from `stderr`
type: boolean
default: false
- name: since
in: query
description: Only return logs since this time, as a UNIX timestamp
type: integer
default: 0
- name: timestamps
in: query
description: Add timestamps to every log line
type: boolean
default: false
- name: tail
in: query
description: 'Only return this number of log lines from the end of the logs.
Specify as an integer or `all` to output all log lines.
'
type: string
default: all
tags:
- Task
definitions:
TaskState:
type: string
enum:
- new
- allocated
- pending
- assigned
- accepted
- preparing
- ready
- starting
- running
- complete
- shutdown
- failed
- rejected
- remove
- orphaned
HealthConfig:
description: 'A test to perform to check that the container is healthy.
Healthcheck commands should be side-effect free.
'
type: object
properties:
Test:
description: 'The test to perform. Possible values are:
- `[]` inherit healthcheck from image or parent image
- `["NONE"]` disable healthcheck
- `["CMD", args...]` exec arguments directly
- `["CMD-SHELL", command]` run command with system''s default shell
A non-zero exit code indicates a failed healthcheck:
- `0` healthy
- `1` unhealthy
- `2` reserved (treated as unhealthy)
- other values: error running probe
'
type: array
items:
type: string
Interval:
description: 'The time to wait between checks in nanoseconds. It should be 0 or at
least 1000000 (1 ms). 0 means inherit.
'
type: integer
format: int64
Timeout:
description: 'The time to wait before considering the check to have hung. It should
be 0 or at least 1000000 (1 ms). 0 means inherit.
If the health check command does not complete within this timeout,
the check is considered failed and the health check process is
forcibly terminated without a graceful shutdown.
'
type: integer
format: int64
Retries:
description: 'The number of consecutive failures needed to consider a container as
unhealthy. 0 means inherit.
'
type: integer
StartPeriod:
description: 'Start period for the container to initialize before starting
health-retries countdown in nanoseconds. It should be 0 or at least
1000000 (1 ms). 0 means inherit.
'
type: integer
format: int64
StartInterval:
description: 'The time to wait between checks in nanoseconds during the start period.
It should be 0 or at least 1000000 (1 ms). 0 means inherit.
'
type: integer
format: int64
ObjectVersion:
description: 'The version number of the object such as node, service, etc. This is needed
to avoid conflicting writes. The client must send the version number along
with the modified specification when updating these objects.
This approach ensures safe concurrency and determinism in that the change
on the object may not be applied if the version number has changed from the
last read. In other words, if two update requests specify the same base
version, only one of the requests can succeed. As a result, two separate
update requests that happen at the same time will not unintentionally
overwrite each other.
'
type: object
properties:
Index:
type: integer
format: uint64
example: 373531
PortStatus:
type: object
description: represents the port status of a task's host ports whose service has published host ports
properties:
Ports:
type: array
items:
$ref: '#/definitions/EndpointPortConfig'
TaskSpec:
description: User modifiable task configuration.
type: object
properties:
PluginSpec:
type: object
description: 'Plugin spec for the service. *(Experimental release only.)*
<p><br /></p>
> **Note**: ContainerSpec, NetworkAttachmentSpec, and PluginSpec are
> mutually exclusive. PluginSpec is only used when the Runtime field
> is set to `plugin`. NetworkAttachmentSpec is used when the Runtime
> field is set to `attachment`.
'
properties:
Name:
description: The name or 'alias' to use for the plugin.
type: string
Remote:
description: The plugin image reference to use.
type: string
Disabled:
description: Disable the plugin once scheduled.
type: boolean
PluginPrivilege:
type: array
items:
$ref: '#/definitions/PluginPrivilege'
ContainerSpec:
type: object
description: 'Container spec for the service.
<p><br /></p>
> **Note**: ContainerSpec, NetworkAttachmentSpec, and PluginSpec are
> mutually exclusive. PluginSpec is only used when the Runtime field
> is set to `plugin`. NetworkAttachmentSpec is used when the Runtime
> field is set to `attachment`.
'
properties:
Image:
description: The image name to use for the container
type: string
Labels:
description: User-defined key/value data.
type: object
additionalProperties:
type: string
Command:
description: The command to be run in the image.
type: array
items:
type: string
Args:
description: Arguments to the command.
type: array
items:
type: string
Hostname:
description: 'The hostname to use for the container, as a valid
[RFC 1123](https://tools.ietf.org/html/rfc1123) hostname.
'
type: string
Env:
description: 'A list of environment variables in the form `VAR=value`.
'
type: array
items:
type: string
Dir:
description: The working directory for commands to run in.
type: string
User:
description: The user inside the container.
type: string
Groups:
type: array
description: 'A list of additional groups that the container process will run as.
'
items:
type: string
Privileges:
type: object
description: Security options for the container
properties:
CredentialSpec:
type: object
description: CredentialSpec for managed service account (Windows only)
properties:
Config:
type: string
example: 0bt9dmxjvjiqermk6xrop3ekq
description: 'Load credential spec from a Swarm Config with the given ID.
The specified config must also be present in the Configs
field with the Runtime property set.
<p><br /></p>
> **Note**: `CredentialSpec.File`, `CredentialSpec.Registry`,
> and `CredentialSpec.Config` are mutually exclusive.
'
File:
type: string
example: spec.json
description: 'Load credential spec from this file. The file is read by
the daemon, and must be present in the `CredentialSpecs`
subdirectory in the docker data directory, which defaults
to `C:\ProgramData\Docker\` on Windows.
For example, specifying `spec.json` loads
`C:\ProgramData\Docker\CredentialSpecs\spec.json`.
<p><br /></p>
> **Note**: `CredentialSpec.File`, `CredentialSpec.Registry`,
> and `CredentialSpec.Config` are mutually exclusive.
'
Registry:
type: string
description: 'Load credential spec from this value in the Windows
registry. The specified registry value must be located in:
`HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs`
<p><br /></p>
> **Note**: `CredentialSpec.File`, `CredentialSpec.Registry`,
> and `CredentialSpec.Config` are mutually exclusive.
'
SELinuxContext:
type: object
description: SELinux labels of the container
properties:
Disable:
type: boolean
description: Disable SELinux
User:
type: string
description: SELinux user label
Role:
type: string
description: SELinux role label
Type:
type: string
description: SELinux type label
Level:
type: string
description: SELinux level label
Seccomp:
type: object
description: Options for configuring seccomp on the container
properties:
Mode:
type: string
enum:
- default
- unconfined
- custom
Profile:
description: The custom seccomp profile as a json object
type: string
AppArmor:
type: object
description: Options for configuring AppArmor on the container
properties:
Mode:
type: string
enum:
- default
- disabled
NoNewPrivileges:
type: boolean
description: Configuration of the no_new_privs bit in the container
TTY:
description: Whether a pseudo-TTY should be allocated.
type: boolean
OpenStdin:
description: Open `stdin`
type: boolean
ReadOnly:
description: Mount the container's root filesystem as read only.
type: boolean
Mounts:
description: 'Specification for mounts to be added to containers created as part
of the service.
'
type: array
items:
$ref: '#/definitions/Mount'
StopSignal:
description: Signal to stop the container.
type: string
StopGracePeriod:
description: 'Amount of time to wait for the container to terminate before
forcefully killing it.
'
type: integer
format: int64
HealthCheck:
$ref: '#/definitions/HealthConfig'
Hosts:
type: array
description: "A list of hostname/IP mappings to add to the container's `hosts`\nfile. The format of extra hosts is specified in the\n[hosts(5)](http://man7.org/linux/man-pages/man5/hosts.5.html)\nman page:\n\n IP_address canonical_hostname [aliases...]\n"
items:
type: string
DNSConfig:
description: 'Specification for DNS related configurations in resolver configuration
file (`resolv.conf`).
'
type: object
properties:
Nameservers:
description: The IP addresses of the name servers.
type: array
items:
type: string
Search:
description: A search list for host-name lookup.
type: array
items:
type: string
Options:
description: 'A list of internal resolver variables to be modified (e.g.,
`debug`, `ndots:3`, etc.).
'
type: array
items:
type: string
Secrets:
description: 'Secrets contains references to zero or more secrets that will be
exposed to the service.
'
type: array
items:
type: object
properties:
File:
description: 'File represents a specific target that is backed by a file.
'
type: object
properties:
Name:
description: 'Name represents the final filename in the filesystem.
'
type: string
UID:
description: UID represents the file UID.
type: string
GID:
description: GID represents the file GID.
type: string
Mode:
description: Mode represents the FileMode of the file.
type: integer
format: uint32
SecretID:
description: 'SecretID represents the ID of the specific secret that we''re
referencing.
'
type: string
SecretName:
description: 'SecretName is the name of the secret that this references,
but this is just provided for lookup/display purposes. The
secret in the reference will be identified by its ID.
'
type: string
OomScoreAdj:
type: integer
format: int64
description: 'An integer value containing the score given to the container in
order to tune OOM killer preferences.
'
example: 0
Configs:
description: 'Configs contains references to zero or more configs that will be
exposed to the service.
'
type: array
items:
type: object
properties:
File:
description: 'File represents a specific target that is backed by a file.
<p><br /><p>
> **Note**: `Configs.File` and `Configs.Runtime` are mutually exclusive
'
type: object
properties:
Name:
description: 'Name represents the final filename in the filesystem.
'
type: string
UID:
description: UID represents the file UID.
type: string
GID:
description: GID represents the file GID.
type: string
Mode:
description: Mode represents the FileMode of the file.
type: integer
format: uint32
Runtime:
description: 'Runtime represents a target that is not mounted into the
container but is used by the task
<p><br /><p>
> **Note**: `Configs.File` and `Configs.Runtime` are mutually
> exclusive
'
type: object
ConfigID:
description: 'ConfigID represents the ID of the specific config that we''re
referencing.
'
type: string
ConfigName:
description: 'ConfigName is the name of the config that this references,
but this is just provided for lookup/display purposes. The
config in the reference will be identified by its ID.
'
type: string
Isolation:
type: string
description: 'Isolation technology of the containers running the service.
(Windows only)
'
enum:
- default
- process
- hyperv
- ''
Init:
description: 'Run an init inside the container that forwards signals and reaps
processes. This field is omitted if empty, and the default (as
configured on the daemon) is used.
'
type: boolean
x-nullable: true
Sysctls:
description: 'Set kernel namedspaced parameters (sysctls) in the container.
The Sysctls option on services accepts the same sysctls as the
are supported on containers. Note that while the same sysctls are
supported, no guarantees or checks are made about their
suitability for a clustered environment, and it''s up to the user
to determine whether a given sysctl will work properly in a
Service.
'
type: object
additionalProperties:
type: string
CapabilityAdd:
type: array
description: 'A list of kernel capabilities to add to the default set
for the container.
'
items:
type: string
example:
- CAP_NET_RAW
- CAP_SYS_ADMIN
- CAP_SYS_CHROOT
- CAP_SYSLOG
CapabilityDrop:
type: array
description: 'A list of kernel capabilities to drop from the default set
for the container.
'
items:
type: string
example:
- CAP_NET_RAW
Ulimits:
description: 'A list of resource limits to set in the container. For example: `{"Name": "nofile", "Soft": 1024, "Hard": 2048}`"
'
type: array
items:
type: object
properties:
Name:
description: Name of ulimit
type: string
Soft:
description: Soft limit
type: integer
Hard:
description: Hard limit
type: integer
NetworkAttachmentSpec:
description: 'Read-only spec type for non-swarm containers attached to swarm overlay
networks.
<p><br /></p>
> **Note**: ContainerSpec, NetworkAttachmentSpec, and PluginSpec are
> mutually exclusive. PluginSpec is only used when the Runtime field
> is set to `plugin`. NetworkAttachmentSpec is used when the Runtime
> field is set to `attachment`.
'
type: object
properties:
ContainerID:
description: ID of the container represented by this task
type: string
Resources:
description: 'Resource requirements which apply to each individual container created
as part of the service.
'
type: object
properties:
Limits:
description: Define resources limits.
$ref: '#/definitions/Limit'
Reservations:
description: Define resources reservation.
$ref: '#/definitions/ResourceObject'
SwapBytes:
description: 'Amount of swap in bytes - can only be used together with a memory limit.
If not specified, the default behaviour is to grant a swap space twice
as big as the memory limit.
Set to -1 to enable unlimited swap.
'
type: integer
format: int64
minimum: -1
x-nullable: true
x-omitempty: true
MemorySwappiness:
description: 'Tune the service''s containers'' memory swappiness (0 to 100).
If not specified, defaults to the containers'' OS'' default, generally 60,
or whatever value was predefined in the image.
Set to -1 to unset a previously set value.
'
type: integer
format: int64
minimum: -1
maximum: 100
x-nullable: true
x-omitempty: true
RestartPolicy:
description: 'Specification for the restart policy which applies to containers
created as part of this service.
'
type: object
properties:
Condition:
description: Condition for restart.
type: string
enum:
- none
- on-failure
- any
Delay:
description: Delay between restart attempts.
type: integer
format: int64
MaxAttempts:
description: 'Maximum attempts to restart a given container before giving up
(default value is 0, which is ignored).
'
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/docker/refs/heads/main/openapi/docker-task-api-openapi.yml