Amazon ECS Task Definitions API

openapi: 3.2.0
info:
  title: Amazon ECS Amazon Elastic Container Service (ECS) Capacity Providers Task Definitions API
  description: Amazon Elastic Container Service (Amazon ECS) is a fully managed container orchestration service that makes it easy to deploy, manage, and scale containerized applications. The Amazon ECS API uses an RPC model where all actions are routed to a single endpoint via POST with an X-Amz-Target header specifying the action. This specification models the core ECS resource operations for clusters, services, tasks, and task definitions.
  version: '3.1'
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/ecs/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  x-apisguru-categories:
  - cloud
  x-logo:
    url: https://aws.amazon.com/favicon.ico
  x-origin:
  - format: openapi
    url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/Welcome.html
servers:
- url: https://ecs.{region}.amazonaws.com
  description: Amazon ECS regional endpoint
  variables:
    region:
      default: us-east-1
      description: AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-north-1
      - ap-southeast-1
      - ap-southeast-2
      - ap-northeast-1
      - ap-northeast-2
      - ap-south-1
      - sa-east-1
      - ca-central-1
security:
- aws_sig_v4: []
tags:
- name: Task Definitions
  description: Operations for managing ECS task definitions
  externalDocs:
    url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RegisterTaskDefinition.html
paths:
  /#X-Amz-Target=AmazonEC2ContainerServiceV20141113.RegisterTaskDefinition:
    post:
      operationId: RegisterTaskDefinition
      summary: Amazon Ecs Register a New Task Definition
      description: Registers a new task definition from the supplied family and container definitions. You can also register task definitions with a volumes parameter for data volumes used by the task containers.
      tags:
      - Task Definitions
      externalDocs:
        url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RegisterTaskDefinition.html
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/RegisterTaskDefinitionRequest'
            examples:
              RegistertaskdefinitionRequestExample:
                summary: Default RegisterTaskDefinition request
                x-microcks-default: true
                value:
                  family: example_value
                  containerDefinitions:
                  - name: Example Title
                    image: example_value
                    cpu: 10
                    memory: 10
                    memoryReservation: 10
                    links: {}
                    portMappings: {}
                    essential: true
                    entryPoint: {}
                    command: {}
                    environment: {}
                    environmentFiles: {}
                    mountPoints: {}
                    volumesFrom: {}
                    secrets: {}
                    dependsOn: {}
                    startTimeout: 10
                    stopTimeout: 10
                    hostname: example_value
                    user: example_value
                    workingDirectory: example_value
                    disableNetworking: true
                    privileged: true
                    readonlyRootFilesystem: true
                    dnsServers: {}
                    dnsSearchDomains: {}
                    extraHosts: {}
                    dockerSecurityOptions: {}
                    interactive: true
                    pseudoTerminal: true
                    dockerLabels: example_value
                    ulimits: {}
                    systemControls: {}
                    resourceRequirements: {}
                    firelensConfiguration: {}
                    repositoryCredentials: {}
                    restartPolicy: {}
                    credentialSpecs: {}
                  taskRoleArn: example_value
                  executionRoleArn: example_value
                  networkMode: bridge
                  volumes:
                  - name: Example Title
                    host: {}
                    dockerVolumeConfiguration: {}
                    efsVolumeConfiguration: {}
                    fsxWindowsFileServerVolumeConfiguration: {}
                  placementConstraints:
                  - type: memberOf
                    expression: example_value
                  requiresCompatibilities:
                  - EC2
                  cpu: example_value
                  memory: example_value
                  tags:
                  - key: example_value
                    value: example_value
                  pidMode: host
                  ipcMode: host
                  proxyConfiguration:
                    type: APPMESH
                    containerName: example_value
                    properties:
                    - {}
                  inferenceAccelerators:
                  - deviceName: example_value
                    deviceType: example_value
                  ephemeralStorage:
                    sizeInGiB: 10
                  runtimePlatform:
                    cpuArchitecture: X86_64
                    operatingSystemFamily: LINUX
                  enableFaultInjection: true
      responses:
        '200':
          description: Task definition registered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  taskDefinition:
                    $ref: '#/components/schemas/TaskDefinition'
                  tags:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tag'
              examples:
                Registertaskdefinition200Example:
                  summary: Default RegisterTaskDefinition 200 response
                  x-microcks-default: true
                  value:
                    taskDefinition:
                      taskDefinitionArn: example_value
                      containerDefinitions:
                      - {}
                      family: example_value
                      taskRoleArn: example_value
                      executionRoleArn: example_value
                      networkMode: bridge
                      revision: 10
                      volumes:
                      - {}
                      status: ACTIVE
                      requiresAttributes:
                      - name: Example Title
                        value: example_value
                        targetType: example_value
                        targetId: '500123'
                      placementConstraints:
                      - {}
                      compatibilities:
                      - EC2
                      requiresCompatibilities:
                      - EC2
                      cpu: example_value
                      memory: example_value
                      pidMode: host
                      ipcMode: host
                      proxyConfiguration:
                        type: APPMESH
                        containerName: example_value
                        properties: {}
                      inferenceAccelerators:
                      - {}
                      ephemeralStorage:
                        sizeInGiB: 10
                      runtimePlatform:
                        cpuArchitecture: X86_64
                        operatingSystemFamily: LINUX
                      registeredAt: 42.5
                      deregisteredAt: 42.5
                      registeredBy: example_value
                      enableFaultInjection: true
                      tags:
                      - {}
                    tags:
                    - key: example_value
                      value: example_value
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#X-Amz-Target=AmazonEC2ContainerServiceV20141113.DeregisterTaskDefinition:
    post:
      operationId: DeregisterTaskDefinition
      summary: Amazon Ecs Deregister a Task Definition
      description: Deregisters the specified task definition by family and revision. Upon deregistration, the task definition is marked as INACTIVE.
      tags:
      - Task Definitions
      externalDocs:
        url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DeregisterTaskDefinition.html
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              type: object
              required:
              - taskDefinition
              properties:
                taskDefinition:
                  type: string
                  description: The family and revision (family:revision) or full ARN of the task definition to deregister.
            examples:
              DeregistertaskdefinitionRequestExample:
                summary: Default DeregisterTaskDefinition request
                x-microcks-default: true
                value:
                  taskDefinition: example_value
      responses:
        '200':
          description: Task definition deregistered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  taskDefinition:
                    $ref: '#/components/schemas/TaskDefinition'
              examples:
                Deregistertaskdefinition200Example:
                  summary: Default DeregisterTaskDefinition 200 response
                  x-microcks-default: true
                  value:
                    taskDefinition:
                      taskDefinitionArn: example_value
                      containerDefinitions:
                      - {}
                      family: example_value
                      taskRoleArn: example_value
                      executionRoleArn: example_value
                      networkMode: bridge
                      revision: 10
                      volumes:
                      - {}
                      status: ACTIVE
                      requiresAttributes:
                      - name: Example Title
                        value: example_value
                        targetType: example_value
                        targetId: '500123'
                      placementConstraints:
                      - {}
                      compatibilities:
                      - EC2
                      requiresCompatibilities:
                      - EC2
                      cpu: example_value
                      memory: example_value
                      pidMode: host
                      ipcMode: host
                      proxyConfiguration:
                        type: APPMESH
                        containerName: example_value
                        properties: {}
                      inferenceAccelerators:
                      - {}
                      ephemeralStorage:
                        sizeInGiB: 10
                      runtimePlatform:
                        cpuArchitecture: X86_64
                        operatingSystemFamily: LINUX
                      registeredAt: 42.5
                      deregisteredAt: 42.5
                      registeredBy: example_value
                      enableFaultInjection: true
                      tags:
                      - {}
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#X-Amz-Target=AmazonEC2ContainerServiceV20141113.DescribeTaskDefinition:
    post:
      operationId: DescribeTaskDefinition
      summary: Amazon Ecs Describe a Task Definition
      description: Describes a task definition. You can specify a family and revision to find information about a specific task definition, or you can simply specify the family to find the latest ACTIVE revision in that family.
      tags:
      - Task Definitions
      externalDocs:
        url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTaskDefinition.html
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              type: object
              required:
              - taskDefinition
              properties:
                taskDefinition:
                  type: string
                  description: The family and revision or full ARN of the task definition to describe.
                include:
                  type: array
                  items:
                    type: string
                    enum:
                    - TAGS
            examples:
              DescribetaskdefinitionRequestExample:
                summary: Default DescribeTaskDefinition request
                x-microcks-default: true
                value:
                  taskDefinition: example_value
                  include:
                  - TAGS
      responses:
        '200':
          description: Task definition described successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  taskDefinition:
                    $ref: '#/components/schemas/TaskDefinition'
                  tags:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tag'
              examples:
                Describetaskdefinition200Example:
                  summary: Default DescribeTaskDefinition 200 response
                  x-microcks-default: true
                  value:
                    taskDefinition:
                      taskDefinitionArn: example_value
                      containerDefinitions:
                      - {}
                      family: example_value
                      taskRoleArn: example_value
                      executionRoleArn: example_value
                      networkMode: bridge
                      revision: 10
                      volumes:
                      - {}
                      status: ACTIVE
                      requiresAttributes:
                      - name: Example Title
                        value: example_value
                        targetType: example_value
                        targetId: '500123'
                      placementConstraints:
                      - {}
                      compatibilities:
                      - EC2
                      requiresCompatibilities:
                      - EC2
                      cpu: example_value
                      memory: example_value
                      pidMode: host
                      ipcMode: host
                      proxyConfiguration:
                        type: APPMESH
                        containerName: example_value
                        properties: {}
                      inferenceAccelerators:
                      - {}
                      ephemeralStorage:
                        sizeInGiB: 10
                      runtimePlatform:
                        cpuArchitecture: X86_64
                        operatingSystemFamily: LINUX
                      registeredAt: 42.5
                      deregisteredAt: 42.5
                      registeredBy: example_value
                      enableFaultInjection: true
                      tags:
                      - {}
                    tags:
                    - key: example_value
                      value: example_value
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#X-Amz-Target=AmazonEC2ContainerServiceV20141113.ListTaskDefinitions:
    post:
      operationId: ListTaskDefinitions
      summary: Amazon Ecs List Task Definitions
      description: Returns a list of task definitions that are registered to your account. You can filter by family name to find all revisions for a specific family.
      tags:
      - Task Definitions
      externalDocs:
        url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ListTaskDefinitions.html
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target'
      requestBody:
        required: false
        content:
          application/x-amz-json-1.1:
            schema:
              type: object
              properties:
                familyPrefix:
                  type: string
                  description: Filter by family name prefix.
                status:
                  type: string
                  enum:
                  - ACTIVE
                  - INACTIVE
                  - DELETE_IN_PROGRESS
                  description: Filter by task definition status.
                sort:
                  type: string
                  enum:
                  - ASC
                  - DESC
                  description: Sort order for results.
                maxResults:
                  type: integer
                  description: Maximum number of results per page (1-100).
                nextToken:
                  type: string
                  description: Pagination token from a previous response.
            examples:
              ListtaskdefinitionsRequestExample:
                summary: Default ListTaskDefinitions request
                x-microcks-default: true
                value:
                  familyPrefix: example_value
                  status: ACTIVE
                  sort: ASC
                  maxResults: 10
                  nextToken: example_value
      responses:
        '200':
          description: Task definitions listed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  taskDefinitionArns:
                    type: array
                    items:
                      type: string
                  nextToken:
                    type: string
              examples:
                Listtaskdefinitions200Example:
                  summary: Default ListTaskDefinitions 200 response
                  x-microcks-default: true
                  value:
                    taskDefinitionArns:
                    - example_value
                    nextToken: example_value
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#X-Amz-Target=AmazonEC2ContainerServiceV20141113.ListTaskDefinitionFamilies:
    post:
      operationId: ListTaskDefinitionFamilies
      summary: Amazon Ecs List Task Definition Families
      description: Returns a list of task definition families that are registered to your account, with ACTIVE task definitions.
      tags:
      - Task Definitions
      externalDocs:
        url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ListTaskDefinitionFamilies.html
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target'
      requestBody:
        required: false
        content:
          application/x-amz-json-1.1:
            schema:
              type: object
              properties:
                familyPrefix:
                  type: string
                  description: Filter by family name prefix.
                status:
                  type: string
                  enum:
                  - ACTIVE
                  - INACTIVE
                  - ALL
                maxResults:
                  type: integer
                nextToken:
                  type: string
            examples:
              ListtaskdefinitionfamiliesRequestExample:
                summary: Default ListTaskDefinitionFamilies request
                x-microcks-default: true
                value:
                  familyPrefix: example_value
                  status: ACTIVE
                  maxResults: 10
                  nextToken: example_value
      responses:
        '200':
          description: Task definition families listed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  families:
                    type: array
                    items:
                      type: string
                  nextToken:
                    type: string
              examples:
                Listtaskdefinitionfamilies200Example:
                  summary: Default ListTaskDefinitionFamilies 200 response
                  x-microcks-default: true
                  value:
                    families:
                    - example_value
                    nextToken: example_value
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#X-Amz-Target=AmazonEC2ContainerServiceV20141113.TagResource:
    post:
      operationId: TagResource
      summary: Amazon Ecs Tag an Ecs Resource
      description: Associates the specified tags to a resource with the specified resourceArn.
      tags:
      - Task Definitions
      externalDocs:
        url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_TagResource.html
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              type: object
              required:
              - resourceArn
              - tags
              properties:
                resourceArn:
                  type: string
                  description: The ARN of the resource to tag.
                tags:
                  type: array
                  items:
                    $ref: '#/components/schemas/Tag'
            examples:
              TagresourceRequestExample:
                summary: Default TagResource request
                x-microcks-default: true
                value:
                  resourceArn: example_value
                  tags:
                  - key: example_value
                    value: example_value
      responses:
        '200':
          description: Resource tagged successfully
          content:
            application/json:
              schema:
                type: object
              examples:
                Tagresource200Example:
                  summary: Default TagResource 200 response
                  x-microcks-default: true
                  value: {}
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#X-Amz-Target=AmazonEC2ContainerServiceV20141113.UntagResource:
    post:
      operationId: UntagResource
      summary: Amazon Ecs Remove Tags From an Ecs Resource
      description: Deletes specified tags from a resource.
      tags:
      - Task Definitions
      externalDocs:
        url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UntagResource.html
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              type: object
              required:
              - resourceArn
              - tagKeys
              properties:
                resourceArn:
                  type: string
                  description: The ARN of the resource to untag.
                tagKeys:
                  type: array
                  items:
                    type: string
                  description: The keys of the tags to remove.
            examples:
              UntagresourceRequestExample:
                summary: Default UntagResource request
                x-microcks-default: true
                value:
                  resourceArn: example_value
                  tagKeys:
                  - example_value
      responses:
        '200':
          description: Tags removed successfully
          content:
            application/json:
              schema:
                type: object
              examples:
                Untagresource200Example:
                  summary: Default UntagResource 200 response
                  x-microcks-default: true
                  value: {}
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#X-Amz-Target=AmazonEC2ContainerServiceV20141113.ListTagsForResource:
    post:
      operationId: ListTagsForResource
      summary: Amazon Ecs List Tags for an Ecs Resource
      description: Lists the tags for the specified resource.
      tags:
      - Task Definitions
      externalDocs:
        url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ListTagsForResource.html
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              type: object
              required:
              - resourceArn
              properties:
                resourceArn:
                  type: string
                  description: The ARN of the resource to list tags for.
            examples:
              ListtagsforresourceRequestExample:
                summary: Default ListTagsForResource request
                x-microcks-default: true
                value:
                  resourceArn: example_value
      responses:
        '200':
          description: Tags listed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  tags:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tag'
              examples:
                Listtagsforresource200Example:
                  summary: Default ListTagsForResource 200 response
                  x-microcks-default: true
                  value:
                    tags:
                    - key: example_value
                      value: example_value
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    LinuxParameters:
      type: object
      properties:
        capabilities:
          type: object
          properties:
            add:
              type: array
              items:
                type: string
            drop:
              type: array
              items:
                type: string
          example: example_value
        devices:
          type: array
          items:
            type: object
            required:
            - hostPath
            properties:
              hostPath:
                type: string
              containerPath:
                type: string
              permissions:
                type: array
                items:
                  type: string
                  enum:
                  - read
                  - write
                  - mknod
          example: []
        initProcessEnabled:
          type: boolean
          description: Run an init process inside the container that forwards signals and reaps processes.
          example: true
        sharedMemorySize:
          type: integer
          description: The value for the size (in MiB) of the /dev/shm volume.
          example: 10
        tmpfs:
          type: array
          items:
            type: object
            required:
            - containerPath
            - size
            properties:
              containerPath:
                type: string
              size:
                type: integer
              mountOptions:
                type: array
                items:
                  type: string
          example: []
        maxSwap:
          type: integer
          description: The total amount of swap memory (in MiB) a container can use.
          example: 10
        swappiness:
          type: integer
          description: The container's memory swappiness behavior. A value of 0 prevents swapping; a value of 100 causes pages to be swapped aggressively.
          minimum: 0
          maximum: 100
          example: 10
    PortMapping:
      type: object
      properties:
        containerPort:
          type: integer
          description: The port number on the container bound to the host port.
          example: 10
        hostPort:
          type: integer
          description: The port number on the container instance to reserve for the container.
          example: 10
        protocol:
          type: string
          description: The protocol used for the port mapping.
          enum:
          - tcp
          - udp
          default: tcp
          example: tcp
        name:
          type: string
          description: The name to use for the port mapping (used with Service Connect).
          example: Example Title
        appProtocol:
          type: string
          description: The application protocol used for the port mapping.
          enum:
          - http
          - http2
          - grpc
          example: http
        containerPortRange:
          type: string
          description: The port number range on the container.
          example: example_value
    KeyValuePair:
      type: object
      properties:
        name:
          type: string
          description: The name of the key-value pair.
          example: Example Title
        value:
          type: string
          description: The value of the key-value pair.
          example: example_value
    EphemeralStorage:
      type: object
      required:
      - sizeInGiB
      properties:
        sizeInGiB:
          type: integer
          description: The total amount, in GiB, of ephemeral storage to set for the task. The minimum supported value is 21 GiB and the maximum supported value is 200 GiB.
          minimum: 21
          maximum: 200
          example: 10
    TaskDefinition:
      type: object
      description: The details of a task definition which describes the container and volume definitions of an Amazon ECS task.
      properties:
        taskDefinitionArn:
          type: string
          description: The full ARN of the task definition.
          example: example_value
        containerDefinitions:
          type: array
          items:
            $ref: '#/components/schemas/ContainerDefinition'
          example: []
        family:
          type: string
          description: The family of your task definition.
          example: example_value
        taskRoleArn:
          type: string
          example: example_value
        executionRoleArn:
          type: string
          example: example_value
        networkMode:
          type: string
          enum:
          - bridge
          - host
          - awsvpc
          - none
          example: bridge
        revision:
          type: integer
          description: The revision of the task in a particular family.
          example: 10
        volumes:
          type: array
          items:
            $ref: '#/components/schemas/Volume'
          example: []
        status:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          - DELETE_IN_PROGRESS
          example: ACTIVE
        requiresAttributes:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
           

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