Docker Task API

openapi: 3.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"
servers:
- url: /v1.54
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
      responses:
        200:
          description: no error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: node is not part of a swarm
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: filters
        in: query
        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>`

          '
        schema:
          type: string
      tags:
      - Task
  /tasks/{id}:
    get:
      summary: Inspect a task
      operationId: TaskInspect
      responses:
        200:
          description: no error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        404:
          description: no such task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: node is not part of a swarm
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: id
        in: path
        description: ID of the task
        required: true
        schema:
          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
      responses:
        200:
          description: logs returned as a stream in response body
          content:
            application/vnd.docker.raw-stream:
              schema:
                type: string
                format: binary
            application/vnd.docker.multiplexed-stream:
              schema:
                type: string
                format: binary
        404:
          description: no such task
          content:
            application/vnd.docker.raw-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/vnd.docker.multiplexed-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: server error
          content:
            application/vnd.docker.raw-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/vnd.docker.multiplexed-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: node is not part of a swarm
          content:
            application/vnd.docker.raw-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/vnd.docker.multiplexed-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the task
        schema:
          type: string
      - name: details
        in: query
        description: Show task context and extra details provided to logs.
        schema:
          type: boolean
          default: false
      - name: follow
        in: query
        description: Keep connection after returning logs.
        schema:
          type: boolean
          default: false
      - name: stdout
        in: query
        description: Return logs from `stdout`
        schema:
          type: boolean
          default: false
      - name: stderr
        in: query
        description: Return logs from `stderr`
        schema:
          type: boolean
          default: false
      - name: since
        in: query
        description: Only return logs since this time, as a UNIX timestamp
        schema:
          type: integer
          default: 0
      - name: timestamps
        in: query
        description: Add timestamps to every log line
        schema:
          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.

          '
        schema:
          type: string
          default: all
      tags:
      - Task
components:
  schemas:
    EndpointPortConfig:
      type: object
      properties:
        Name:
          type: string
        Protocol:
          type: string
          enum:
          - tcp
          - udp
          - sctp
        TargetPort:
          description: The port inside the container.
          type: integer
        PublishedPort:
          description: The port on the swarm hosts.
          type: integer
        PublishMode:
          description: "The mode in which port is published.\n\n<p><br /></p>\n\n- \"ingress\" makes the target port accessible on every node,\n  regardless of whether there is a task for the service running on\n  that node or not.\n- \"host\" bypasses the routing mesh and publish the port directly on\n  the swarm node where that service is running.\n"
          type: string
          enum:
          - ingress
          - host
          default: ingress
          example: ingress
    ErrorResponse:
      description: Represents an error.
      type: object
      required:
      - message
      properties:
        message:
          description: The error message.
          type: string
      example:
        message: Something went wrong.
    Limit:
      description: 'An object describing a limit on resources which can be requested by a task.

        '
      type: object
      properties:
        NanoCPUs:
          type: integer
          format: int64
          example: 4000000000
        MemoryBytes:
          type: integer
          format: int64
          example: 8272408576
        Pids:
          description: 'Limits the maximum number of PIDs in the container. Set `0` for unlimited.

            '
          type: integer
          format: int64
          default: 0
          example: 100
    Mount:
      type: object
      properties:
        Target:
          description: Container path.
          type: string
        Source:
          description: 'Mount source (e.g. a volume name, a host path). The source cannot be

            specified when using `Type=tmpfs`. For `Type=bind`, the source path

            must either exist, or the `CreateMountpoint` must be set to `true` to

            create the source path on the host if missing.


            For `Type=npipe`, the pipe must exist prior to creating the container.'
          type: string
        Type:
          description: 'The mount type. Available types:


            - `bind` Mounts a file or directory from the host into the container. The `Source` must exist prior to creating the container.

            - `cluster` a Swarm cluster volume

            - `image` Mounts an image.

            - `npipe` Mounts a named pipe from the host into the container. The `Source` must exist prior to creating the container.

            - `tmpfs` Create a tmpfs with the given options. The mount `Source` cannot be specified for tmpfs.

            - `volume` Creates a volume with the given name and options (or uses a pre-existing volume with the same name and options). These are **not** removed when the container is removed.

            '
          allOf:
          - $ref: '#/components/schemas/MountType'
        ReadOnly:
          description: Whether the mount should be read-only.
          type: boolean
        Consistency:
          description: 'The consistency requirement for the mount: `default`, `consistent`, `cached`, or `delegated`.'
          type: string
        BindOptions:
          description: Optional configuration for the `bind` type.
          type: object
          properties:
            Propagation:
              description: A propagation mode with the value `[r]private`, `[r]shared`, or `[r]slave`.
              type: string
              enum:
              - private
              - rprivate
              - shared
              - rshared
              - slave
              - rslave
            NonRecursive:
              description: Disable recursive bind mount.
              type: boolean
              default: false
            CreateMountpoint:
              description: Create mount point on host if missing
              type: boolean
              default: false
            ReadOnlyNonRecursive:
              description: 'Make the mount non-recursively read-only, but still leave the mount recursive

                (unless NonRecursive is set to `true` in conjunction).


                Added in v1.44, before that version all read-only mounts were

                non-recursive by default. To match the previous behaviour this

                will default to `true` for clients on versions prior to v1.44.

                '
              type: boolean
              default: false
            ReadOnlyForceRecursive:
              description: Raise an error if the mount cannot be made recursively read-only.
              type: boolean
              default: false
        VolumeOptions:
          description: Optional configuration for the `volume` type.
          type: object
          properties:
            NoCopy:
              description: Populate volume with data from the target.
              type: boolean
              default: false
            Labels:
              description: User-defined key/value metadata.
              type: object
              additionalProperties:
                type: string
            DriverConfig:
              description: Map of driver specific options
              type: object
              properties:
                Name:
                  description: Name of the driver to use to create the volume.
                  type: string
                Options:
                  description: key/value map of driver specific options.
                  type: object
                  additionalProperties:
                    type: string
            Subpath:
              description: Source path inside the volume. Must be relative without any back traversals.
              type: string
              example: dir-inside-volume/subdirectory
        ImageOptions:
          description: Optional configuration for the `image` type.
          type: object
          properties:
            Subpath:
              description: Source path inside the image. Must be relative without any back traversals.
              type: string
              example: dir-inside-image/subdirectory
        TmpfsOptions:
          description: Optional configuration for the `tmpfs` type.
          type: object
          properties:
            SizeBytes:
              description: The size for the tmpfs mount in bytes.
              type: integer
              format: int64
            Mode:
              description: 'The permission mode for the tmpfs mount in an integer.

                The value must not be in octal format (e.g. 755) but rather

                the decimal representation of the octal value (e.g. 493).

                '
              type: integer
            Options:
              description: 'The options to be passed to the tmpfs mount. An array of arrays.

                Flag options should be provided as 1-length arrays. Other types

                should be provided as as 2-length arrays, where the first item is

                the key and the second the value.

                '
              type: array
              items:
                type: array
                minItems: 1
                maxItems: 2
                items:
                  type: string
              example:
              - - noexec
    Platform:
      description: 'Platform represents the platform (Arch/OS).

        '
      type: object
      properties:
        Architecture:
          description: 'Architecture represents the hardware architecture (for example,

            `x86_64`).

            '
          type: string
          example: x86_64
        OS:
          description: 'OS represents the Operating System (for example, `linux` or `windows`).

            '
          type: string
          example: linux
    ResourceObject:
      description: 'An object describing the resources which can be advertised by a node and

        requested by a task.

        '
      type: object
      properties:
        NanoCPUs:
          type: integer
          format: int64
          example: 4000000000
        MemoryBytes:
          type: integer
          format: int64
          example: 8272408576
        GenericResources:
          $ref: '#/components/schemas/GenericResources'
    TaskStatus:
      type: object
      description: represents the status of a task.
      properties:
        Timestamp:
          type: string
          format: dateTime
        State:
          $ref: '#/components/schemas/TaskState'
        Message:
          type: string
        Err:
          type: string
        ContainerStatus:
          $ref: '#/components/schemas/ContainerStatus'
        PortStatus:
          $ref: '#/components/schemas/PortStatus'
    ContainerStatus:
      type: object
      description: represents the status of a container.
      properties:
        ContainerID:
          type: string
        PID:
          type: integer
        ExitCode:
          type: integer
    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: '#/components/schemas/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: '#/components/schemas/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: '#/components/schemas/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:
  

# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/docker/refs/heads/main/openapi/docker-task-api-openapi.yml