AWS Fargate Tasks API

openapi: 3.1.0
info:
  title: AWS Fargate Amazon ECS API (Fargate) Clusters Tasks API
  description: The Amazon ECS API provides programmatic access to manage Fargate tasks and services through Amazon Elastic Container Service. AWS Fargate is a serverless compute engine for containers that removes the need to provision and manage servers. This specification covers the core ECS API operations relevant to Fargate workloads, including registering task definitions with Fargate compatibility, running tasks on Fargate infrastructure, and managing services with the Fargate launch type. All operations use the JSON-RPC style with POST requests and an X-Amz-Target header specifying the action.
  version: '2014-11-13'
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/fargate/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  termsOfService: https://aws.amazon.com/service-terms/
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: Tasks
  description: Operations for running and managing individual Fargate tasks, including launching tasks, stopping tasks, and querying task status.
  externalDocs:
    url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html
paths:
  /#X-Amz-Target=AmazonEC2ContainerServiceV20141113.RunTask:
    post:
      operationId: runTask
      summary: AWS Fargate Run a Fargate task
      description: Starts a new task using the specified task definition. When using the Fargate launch type, tasks run on AWS Fargate serverless infrastructure without the need to manage servers. The networkConfiguration parameter with awsvpcConfiguration is required for Fargate tasks. You can optionally specify a platformVersion, which defaults to LATEST. Each RunTask call can launch up to 10 tasks.
      tags:
      - Tasks
      externalDocs:
        url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/RunTaskRequest'
      responses:
        '200':
          description: Task launched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunTaskResponse'
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
  /#X-Amz-Target=AmazonEC2ContainerServiceV20141113.StopTask:
    post:
      operationId: stopTask
      summary: AWS Fargate Stop a running task
      description: Stops a running task. When you call StopTask on a Fargate task, the equivalent of docker stop is issued to the containers running in the task. This results in a SIGTERM value and a default 30-second timeout, after which the SIGKILL value is sent and the containers are forcibly stopped. The task transitions through STOPPING to STOPPED.
      tags:
      - Tasks
      externalDocs:
        url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_StopTask.html
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              type: object
              required:
              - task
              properties:
                cluster:
                  type: string
                  description: The short name or full ARN of the cluster that hosts the task to stop.
                task:
                  type: string
                  description: The task ID or full ARN of the task to stop.
                reason:
                  type: string
                  description: An optional message that explains why the task was stopped.
      responses:
        '200':
          description: Task stop initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  task:
                    $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
  /#X-Amz-Target=AmazonEC2ContainerServiceV20141113.DescribeTasks:
    post:
      operationId: describeTasks
      summary: AWS Fargate Describe one or more tasks
      description: Describes a specified task or tasks. Returns detailed information about each task, including its current status, launch type, platform version, container details, and network configuration. Up to 100 tasks can be described in a single call.
      tags:
      - Tasks
      externalDocs:
        url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              type: object
              required:
              - tasks
              properties:
                cluster:
                  type: string
                  description: The short name or full ARN of the cluster that hosts the tasks to describe.
                tasks:
                  type: array
                  description: A list of up to 100 task IDs or full ARNs.
                  items:
                    type: string
                  maxItems: 100
                include:
                  type: array
                  description: Specifies whether to include resource tags for the tasks.
                  items:
                    type: string
                    enum:
                    - TAGS
      responses:
        '200':
          description: Tasks described successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  tasks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
                  failures:
                    type: array
                    items:
                      $ref: '#/components/schemas/Failure'
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
  /#X-Amz-Target=AmazonEC2ContainerServiceV20141113.ListTasks:
    post:
      operationId: listTasks
      summary: AWS Fargate List tasks in a cluster
      description: Returns a list of tasks. You can filter the results by cluster, service, family, or launch type. Specify launchType FARGATE to list only Fargate tasks. Tasks can also be filtered by desired status or started-by value.
      tags:
      - Tasks
      externalDocs:
        url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ListTasks.html
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              type: object
              properties:
                cluster:
                  type: string
                  description: The short name or full ARN of the cluster to list tasks from.
                serviceName:
                  type: string
                  description: The name of the service to filter tasks by.
                family:
                  type: string
                  description: The task definition family name to filter with.
                launchType:
                  type: string
                  description: The launch type to filter tasks by.
                  enum:
                  - EC2
                  - FARGATE
                  - EXTERNAL
                desiredStatus:
                  type: string
                  description: The task desired status to filter with.
                  enum:
                  - RUNNING
                  - PENDING
                  - STOPPED
                startedBy:
                  type: string
                  description: The startedBy value to filter tasks by.
                nextToken:
                  type: string
                  description: Token for the next set of results.
                maxResults:
                  type: integer
                  description: Maximum number of task results.
                  minimum: 1
                  maximum: 100
      responses:
        '200':
          description: List of task ARNs
          content:
            application/json:
              schema:
                type: object
                properties:
                  taskArns:
                    type: array
                    items:
                      type: string
                  nextToken:
                    type: string
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
  /#X-Amz-Target=AmazonEC2ContainerServiceV20141113.ExecuteCommand:
    post:
      operationId: executeCommand
      summary: AWS Fargate Execute a command in a Fargate task container
      description: Runs a command remotely and securely inside a container running on a Fargate task. ECS Exec uses AWS Systems Manager Session Manager to establish a connection with the container and uses AWS IAM policies to control access. The task must have been launched with enableExecuteCommand set to true.
      tags:
      - Tasks
      externalDocs:
        url: https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ExecuteCommand.html
      parameters:
      - $ref: '#/components/parameters/X-Amz-Target'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              type: object
              required:
              - command
              - interactive
              - task
              properties:
                cluster:
                  type: string
                  description: The short name or full ARN of the cluster the task is running in.
                container:
                  type: string
                  description: The name of the container to execute the command in. If not specified, the first essential container is used.
                command:
                  type: string
                  description: The command to run inside the container.
                interactive:
                  type: boolean
                  description: Whether to run the command in interactive mode.
                task:
                  type: string
                  description: The task ID or full ARN of the task to run the command in.
      responses:
        '200':
          description: Command session initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  clusterArn:
                    type: string
                  containerArn:
                    type: string
                  containerName:
                    type: string
                  interactive:
                    type: boolean
                  session:
                    type: object
                    properties:
                      sessionId:
                        type: string
                      streamUrl:
                        type: string
                      tokenValue:
                        type: string
                  taskArn:
                    type: string
        '400':
          $ref: '#/components/responses/ClientError'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    TaskOverride:
      type: object
      description: The overrides associated with a task, used to override task definition values at runtime.
      properties:
        containerOverrides:
          type: array
          description: The container overrides for the task.
          items:
            type: object
            properties:
              name:
                type: string
                description: The name of the container to override.
              command:
                type: array
                items:
                  type: string
              environment:
                type: array
                items:
                  $ref: '#/components/schemas/KeyValuePair'
              cpu:
                type: integer
              memory:
                type: integer
              memoryReservation:
                type: integer
        cpu:
          type: string
          description: The CPU override for the task.
        memory:
          type: string
          description: The memory override for the task.
        taskRoleArn:
          type: string
          description: The IAM role override for the task.
        executionRoleArn:
          type: string
          description: The task execution role override.
        ephemeralStorage:
          $ref: '#/components/schemas/EphemeralStorage'
    EphemeralStorage:
      type: object
      description: The amount of ephemeral storage to allocate for the Fargate task. Available on platform version 1.4.0 or later for Linux and 1.0.0 or later for Windows.
      required:
      - sizeInGiB
      properties:
        sizeInGiB:
          type: integer
          description: The total amount of ephemeral storage in GiB.
          minimum: 21
          maximum: 200
    AwsVpcConfiguration:
      type: object
      description: The VPC networking configuration for Fargate tasks, which always use the awsvpc network mode.
      required:
      - subnets
      properties:
        subnets:
          type: array
          description: The IDs of the subnets associated with the task or service. All specified subnets must be in the same VPC.
          items:
            type: string
        securityGroups:
          type: array
          description: The IDs of the security groups associated with the task or service. If no security group is specified, the default security group for the VPC is used.
          items:
            type: string
          maxItems: 5
        assignPublicIp:
          type: string
          description: Whether the task's elastic network interface receives a public IP address. A value of ENABLED is required when using public subnets so Fargate tasks can pull container images.
          enum:
          - ENABLED
          - DISABLED
    Task:
      type: object
      description: Details of a running or stopped Fargate task.
      properties:
        taskArn:
          type: string
          description: The ARN of the task.
        clusterArn:
          type: string
          description: The ARN of the cluster that hosts the task.
        taskDefinitionArn:
          type: string
          description: The ARN of the task definition that the task is using.
        launchType:
          type: string
          description: The infrastructure that the task runs on.
          enum:
          - FARGATE
          - EC2
          - EXTERNAL
        platformVersion:
          type: string
          description: The Fargate platform version on which the task runs.
        platformFamily:
          type: string
          description: The operating system the task runs on.
        lastStatus:
          type: string
          description: The last known status of the task.
        desiredStatus:
          type: string
          description: The desired status of the task.
        cpu:
          type: string
          description: The CPU units used by the task.
        memory:
          type: string
          description: The memory in MiB used by the task.
        containers:
          type: array
          description: The containers associated with the task.
          items:
            $ref: '#/components/schemas/Container'
        overrides:
          $ref: '#/components/schemas/TaskOverride'
        group:
          type: string
          description: The name of the task group associated with the task.
        availabilityZone:
          type: string
          description: The Availability Zone where the task is running.
        connectivity:
          type: string
          description: The connectivity status of the task.
          enum:
          - CONNECTED
          - DISCONNECTED
        healthStatus:
          type: string
          description: The health status of the task.
          enum:
          - HEALTHY
          - UNHEALTHY
          - UNKNOWN
        enableExecuteCommand:
          type: boolean
          description: Whether ECS Exec is enabled for the task.
        startedBy:
          type: string
          description: The tag specified when the task was started.
        stoppedReason:
          type: string
          description: The reason the task was stopped.
        createdAt:
          type: string
          format: date-time
          description: The Unix timestamp when the task was created.
        startedAt:
          type: string
          format: date-time
          description: The Unix timestamp when the task started.
        stoppedAt:
          type: string
          format: date-time
          description: The Unix timestamp when the task was stopped.
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        ephemeralStorage:
          $ref: '#/components/schemas/EphemeralStorage'
    Failure:
      type: object
      description: A failed resource from a batch operation.
      properties:
        arn:
          type: string
          description: The ARN of the failed resource.
        reason:
          type: string
          description: The reason for the failure.
        detail:
          type: string
          description: The details of the failure.
    NetworkConfiguration:
      type: object
      description: The network configuration for a task or service. Required for Fargate tasks and services.
      properties:
        awsvpcConfiguration:
          $ref: '#/components/schemas/AwsVpcConfiguration'
    CapacityProviderStrategyItem:
      type: object
      description: A capacity provider strategy item specifying a capacity provider and its weight and base values. Use FARGATE or FARGATE_SPOT for serverless compute.
      required:
      - capacityProvider
      properties:
        capacityProvider:
          type: string
          description: The short name of the capacity provider. Valid Fargate values are FARGATE and FARGATE_SPOT.
        weight:
          type: integer
          description: The relative percentage of the total number of tasks that should use the specified capacity provider.
          minimum: 0
          maximum: 1000
        base:
          type: integer
          description: The number of tasks, at minimum, to run on the specified capacity provider. Only one capacity provider in a strategy can have a base defined.
          minimum: 0
          maximum: 100000
    Container:
      type: object
      description: A container running as part of a task.
      properties:
        containerArn:
          type: string
          description: The ARN of the container.
        taskArn:
          type: string
          description: The ARN of the task the container is part of.
        name:
          type: string
          description: The name of the container.
        image:
          type: string
          description: The image used for the container.
        imageDigest:
          type: string
          description: The container image manifest digest.
        lastStatus:
          type: string
          description: The last known status of the container.
        exitCode:
          type: integer
          description: The exit code returned from the container.
        healthStatus:
          type: string
          description: The health status of the container.
          enum:
          - HEALTHY
          - UNHEALTHY
          - UNKNOWN
        networkInterfaces:
          type: array
          description: The network interfaces associated with the container.
          items:
            type: object
            properties:
              attachmentId:
                type: string
              privateIpv4Address:
                type: string
              ipv6Address:
                type: string
        networkBindings:
          type: array
          description: The network bindings associated with the container.
          items:
            type: object
            properties:
              bindIP:
                type: string
              containerPort:
                type: integer
              hostPort:
                type: integer
              protocol:
                type: string
    ErrorResponse:
      type: object
      properties:
        __type:
          type: string
          description: The error type identifier.
        message:
          type: string
          description: A human-readable error message.
    RunTaskResponse:
      type: object
      properties:
        tasks:
          type: array
          description: The tasks that were started.
          items:
            $ref: '#/components/schemas/Task'
        failures:
          type: array
          description: Any failures associated with the call.
          items:
            $ref: '#/components/schemas/Failure'
    KeyValuePair:
      type: object
      description: A key-value pair representing an environment variable.
      properties:
        name:
          type: string
          description: The name of the environment variable.
        value:
          type: string
          description: The value of the environment variable.
    Tag:
      type: object
      description: A key-value pair used to tag an Amazon ECS resource.
      properties:
        key:
          type: string
          description: The tag key. Tag keys are case-sensitive and must be unique.
          maxLength: 128
        value:
          type: string
          description: The tag value.
          maxLength: 256
    RunTaskRequest:
      type: object
      description: Request to run a Fargate task.
      required:
      - taskDefinition
      properties:
        cluster:
          type: string
          description: The short name or full ARN of the cluster on which to run the task. If not specified, the default cluster is used.
        taskDefinition:
          type: string
          description: The family and revision (family:revision) or full ARN of the task definition to run.
        count:
          type: integer
          description: The number of instantiations of the task to place. Maximum 10.
          minimum: 1
          maximum: 10
          default: 1
        launchType:
          type: string
          description: The infrastructure to run the task on. Use FARGATE for serverless compute.
          enum:
          - FARGATE
          - EC2
          - EXTERNAL
        capacityProviderStrategy:
          type: array
          description: The capacity provider strategy for the task. Cannot be used with launchType. Use FARGATE and FARGATE_SPOT providers.
          items:
            $ref: '#/components/schemas/CapacityProviderStrategyItem'
        platformVersion:
          type: string
          description: The Fargate platform version to run the task on. Defaults to LATEST.
          default: LATEST
        networkConfiguration:
          $ref: '#/components/schemas/NetworkConfiguration'
        overrides:
          $ref: '#/components/schemas/TaskOverride'
        enableExecuteCommand:
          type: boolean
          description: Whether to enable ECS Exec for the tasks, allowing you to run commands inside the containers.
        enableECSManagedTags:
          type: boolean
          description: Whether to enable Amazon ECS managed tags for the task.
        propagateTags:
          type: string
          description: Specifies whether to propagate tags from the task definition to the task.
          enum:
          - TASK_DEFINITION
          - SERVICE
          - NONE
        group:
          type: string
          description: The name of the task group to associate with the task.
        startedBy:
          type: string
          description: An optional tag to identify who started the task.
        clientToken:
          type: string
          description: An identifier to ensure the idempotency of the request.
        tags:
          type: array
          description: Tags to apply to the task.
          items:
            $ref: '#/components/schemas/Tag'
  parameters:
    X-Amz-Target:
      name: X-Amz-Target
      in: header
      required: true
      schema:
        type: string
      description: The ECS API action target header used for JSON-RPC style routing.
  responses:
    ServerError:
      description: Server error. An internal service error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ClientError:
      description: Client error. The request was invalid, contained incorrect parameters, or the caller does not have required permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    aws_sig_v4:
      type: apiKey
      name: Authorization
      in: header
      description: AWS Signature Version 4 authentication. Requests must be signed using AWS access credentials.
externalDocs:
  description: AWS Fargate Developer Guide
  url: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html