Amazon EC2 Instances API

openapi: 3.1.0
info:
  title: Amazon EC2 AMIs Instances API
  description: Amazon Elastic Compute Cloud (EC2) provides resizable compute capacity in the cloud. This API enables you to launch and manage virtual server instances, configure networking and security, and manage storage volumes with complete control over your computing resources.
  version: '2016-11-15'
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  termsOfService: https://aws.amazon.com/service-terms/
servers:
- url: https://ec2.{region}.amazonaws.com
  description: Amazon EC2 Regional Endpoint
  variables:
    region:
      default: us-east-1
      description: AWS Region
security:
- sigv4Auth: []
tags:
- name: Instances
  description: Operations for launching, managing, and terminating EC2 instances
paths:
  /?Action=RunInstances:
    get:
      operationId: runInstances
      summary: Amazon EC2 Launch EC2 Instances
      description: Launches the specified number of instances using an AMI for which you have permissions. You can specify a number of options, or leave the default options. When you launch an instance, it enters the pending state, then the running state.
      tags:
      - Instances
      parameters:
      - $ref: '#/components/parameters/ImageId'
      - $ref: '#/components/parameters/InstanceType'
      - name: MinCount
        in: query
        required: true
        description: The minimum number of instances to launch
        schema:
          type: integer
          minimum: 1
        example: 1
      - name: MaxCount
        in: query
        required: true
        description: The maximum number of instances to launch
        schema:
          type: integer
          minimum: 1
        example: 1
      - name: KeyName
        in: query
        description: The name of the key pair to use for SSH access
        schema:
          type: string
        example: example-resource-name
      - name: SecurityGroupId
        in: query
        description: The IDs of the security groups
        schema:
          type: array
          items:
            type: string
        example:
        - example-cluster-01
      - name: SubnetId
        in: query
        description: The ID of the subnet to launch the instance into
        schema:
          type: string
        example: example-id-1234
      responses:
        '200':
          description: Successfully launched instances
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/RunInstancesResponse'
              examples:
                runInstances200Example:
                  summary: Default runInstances 200 response
                  x-microcks-default: true
                  value:
                    reservationId: example-id-1234
                    ownerId: example-id-1234
                    instances:
                    - i-0abc123def456789
        '400':
          description: Invalid request parameters
        '401':
          description: Authentication failure
        '403':
          description: Authorization failure
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=DescribeInstances:
    get:
      operationId: describeInstances
      summary: Amazon EC2 Describe EC2 Instances
      description: Describes the specified instances or all instances. Returns information about the instances including instance ID, instance type, launch time, placement, monitoring state, and more.
      tags:
      - Instances
      parameters:
      - name: InstanceId
        in: query
        description: The instance IDs to describe
        schema:
          type: array
          items:
            type: string
        example:
        - i-0abc123def456789
      - name: Filter
        in: query
        description: Filters to apply to the results
        schema:
          type: array
          items:
            type: string
        example:
        - example-string
      - name: MaxResults
        in: query
        description: Maximum number of results to return
        schema:
          type: integer
          minimum: 5
          maximum: 1000
        example: 1
      - name: NextToken
        in: query
        description: Token for the next page of results
        schema:
          type: string
        example: example-string
      responses:
        '200':
          description: Successfully described instances
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/DescribeInstancesResponse'
              examples:
                describeInstances200Example:
                  summary: Default describeInstances 200 response
                  x-microcks-default: true
                  value:
                    reservationSet:
                    - reservationId: example-id-1234
                      instancesSet:
                      - example
                    nextToken: example-string
        '400':
          description: Invalid request parameters
        '401':
          description: Authentication failure
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=StartInstances:
    get:
      operationId: startInstances
      summary: Amazon EC2 Start Stopped Instances
      description: Starts an Amazon EBS-backed instance that you have previously stopped. Instances that use Amazon EBS volumes as their root devices can be quickly stopped and started.
      tags:
      - Instances
      parameters:
      - name: InstanceId
        in: query
        required: true
        description: The IDs of the instances to start
        schema:
          type: array
          items:
            type: string
        example:
        - i-0abc123def456789
      responses:
        '200':
          description: Successfully started instances
        '400':
          description: Invalid request parameters
        '401':
          description: Authentication failure
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=StopInstances:
    get:
      operationId: stopInstances
      summary: Amazon EC2 Stop Running Instances
      description: Stops an Amazon EBS-backed instance. You can use the stopped instance to modify the root volume, change instance type, or attach additional EBS volumes.
      tags:
      - Instances
      parameters:
      - name: InstanceId
        in: query
        required: true
        description: The IDs of the instances to stop
        schema:
          type: array
          items:
            type: string
        example:
        - i-0abc123def456789
      - name: Force
        in: query
        description: Forces the instances to stop without graceful shutdown
        schema:
          type: boolean
        example: true
      responses:
        '200':
          description: Successfully stopped instances
        '400':
          description: Invalid request parameters
        '401':
          description: Authentication failure
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=TerminateInstances:
    get:
      operationId: terminateInstances
      summary: Amazon EC2 Terminate Instances
      description: Shuts down the specified instances. This operation is idempotent; if you terminate an instance more than once, each call succeeds. Terminated instances remain visible for a short period after termination.
      tags:
      - Instances
      parameters:
      - name: InstanceId
        in: query
        required: true
        description: The IDs of the instances to terminate
        schema:
          type: array
          items:
            type: string
        example:
        - i-0abc123def456789
      responses:
        '200':
          description: Successfully terminated instances
        '400':
          description: Invalid request parameters
        '401':
          description: Authentication failure
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=RebootInstances:
    get:
      operationId: rebootInstances
      summary: Amazon EC2 Reboot Instances
      description: Requests a reboot of the specified instances. This operation is asynchronous; it only queues a request to reboot the specified instances.
      tags:
      - Instances
      parameters:
      - name: InstanceId
        in: query
        required: true
        description: The IDs of the instances to reboot
        schema:
          type: array
          items:
            type: string
        example:
        - i-0abc123def456789
      responses:
        '200':
          description: Successfully requested instance reboot
        '400':
          description: Invalid request parameters
        '401':
          description: Authentication failure
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /?Action=DescribeInstanceStatus:
    get:
      operationId: describeInstanceStatus
      summary: Amazon EC2 Describe Instance Status
      description: Describes the status of the specified instances or all of your instances. Instance status includes status checks, scheduled events, and instance state information.
      tags:
      - Instances
      parameters:
      - name: InstanceId
        in: query
        description: The instance IDs to describe
        schema:
          type: array
          items:
            type: string
        example:
        - i-0abc123def456789
      - name: IncludeAllInstances
        in: query
        description: Include all instances regardless of running state
        schema:
          type: boolean
        example: true
      responses:
        '200':
          description: Successfully described instance status
        '400':
          description: Invalid request parameters
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    RunInstancesResponse:
      type: object
      description: Response from the RunInstances action
      properties:
        reservationId:
          type: string
          description: The ID of the reservation
          example: example-id-1234
        ownerId:
          type: string
          description: The ID of the AWS account that owns the reservation
          example: example-id-1234
        instances:
          type: array
          description: The instances launched
          items:
            $ref: '#/components/schemas/Instance'
          example:
          - i-0abc123def456789
    Tag:
      type: object
      description: Describes a tag
      properties:
        key:
          type: string
          description: The key of the tag
          example: example-string
        value:
          type: string
          description: The value of the tag
          example: example-string
    Instance:
      type: object
      description: Describes an EC2 instance
      properties:
        instanceId:
          type: string
          description: The ID of the instance
          example: i-0abc123def456789
        imageId:
          type: string
          description: The ID of the AMI used to launch the instance
          example: ami-0abc123def456789
        instanceType:
          type: string
          description: The instance type
          example: i-0abc123def456789
        keyName:
          type: string
          description: The name of the key pair
          example: example-resource-name
        launchTime:
          type: string
          format: date-time
          description: The time the instance was launched
          example: '2025-03-15T14:30:00Z'
        placement:
          type: object
          description: The location where the instance launched
          properties:
            availabilityZone:
              type: string
              description: The Availability Zone of the instance
          example:
            availabilityZone: example-string
        monitoring:
          type: object
          description: The monitoring for the instance
          properties:
            state:
              type: string
              description: The monitoring state
              enum:
              - disabled
              - disabling
              - enabled
              - pending
          example:
            state: disabled
        instanceState:
          type: object
          description: The current state of the instance
          properties:
            code:
              type: integer
              description: The state code (0=pending, 16=running, 32=shutting-down, 48=terminated, 64=stopping, 80=stopped)
            name:
              type: string
              description: The current state of the instance
              enum:
              - pending
              - running
              - shutting-down
              - terminated
              - stopping
              - stopped
          example:
            code: 1
            name: pending
        subnetId:
          type: string
          description: The ID of the subnet in which the instance is running
          example: example-id-1234
        vpcId:
          type: string
          description: The ID of the VPC in which the instance is running
          example: example-id-1234
        privateIpAddress:
          type: string
          description: The private IPv4 address assigned to the instance
          example: example-string
        publicIpAddress:
          type: string
          description: The public IPv4 address assigned to the instance
          example: example-string
        architecture:
          type: string
          description: The architecture of the image
          enum:
          - i386
          - x86_64
          - arm64
          example: i386
        rootDeviceType:
          type: string
          description: The root device type used by the AMI
          enum:
          - ebs
          - instance-store
          example: ebs
        tags:
          type: array
          description: Any tags assigned to the instance
          items:
            $ref: '#/components/schemas/Tag'
          example:
          - example-string
        securityGroups:
          type: array
          description: The security groups for the instance
          items:
            type: object
            properties:
              groupId:
                type: string
                description: The ID of the security group
              groupName:
                type: string
                description: The name of the security group
          example:
          - groupId: example-cluster-01
            groupName: example-cluster-01
    DescribeInstancesResponse:
      type: object
      description: Response from the DescribeInstances action
      properties:
        reservationSet:
          type: array
          description: Information about the reservations
          items:
            type: object
            properties:
              reservationId:
                type: string
                description: The ID of the reservation
              instancesSet:
                type: array
                items:
                  $ref: '#/components/schemas/Instance'
          example:
          - reservationId: example-id-1234
            instancesSet:
            - example
        nextToken:
          type: string
          description: Token for the next page of results
          example: example-string
  parameters:
    InstanceType:
      name: InstanceType
      in: query
      description: The instance type such as t2.micro, m5.large, c5.xlarge
      schema:
        type: string
    ImageId:
      name: ImageId
      in: query
      required: true
      description: The ID of the AMI to launch
      schema:
        type: string
  securitySchemes:
    sigv4Auth:
      type: apiKey
      name: Authorization
      in: header
      description: AWS Signature Version 4 authentication
externalDocs:
  description: Amazon EC2 API Reference
  url: https://docs.aws.amazon.com/AWSEC2/latest/APIReference/