Amazon Systems Manager Automation API

Operations for managing automation executions.

GitHub OpenAPI
Business capability
IT Operations Management BC-600.40

Operations 1

POST /#StartAutomationExecution Start Automation Execution #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/amazon-systems-manager:amazon-systems-manager-automation-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

amazon-systems-manager-automation-api-openapi.yml Raw ↑
openapi: 3.1.0
info:
  title: Amazon Simple Systems Manager (SSM) Automation API
  version: '2014-11-06'
  description: Generated from AWS's published Smithy model for Amazon Simple Systems Manager (SSM). 1 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://ssm.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /#StartAutomationExecution:
    post:
      operationId: StartAutomationExecution
      summary: Start Automation Execution
      description: Initiates execution of an Automation runbook.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/StartAutomationExecutionResult'
        '400':
          description: AutomationDefinitionNotFoundException; AutomationDefinitionVersionNotFoundException; AutomationExecutionLimitExceededException;
            IdempotentParameterMismatch; InvalidAutomationExecutionParametersException; InvalidTarget
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/AutomationDefinitionNotFoundException'
        '500':
          description: InternalServerError
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - AmazonSSM.StartAutomationExecution
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/StartAutomationExecutionRequest'
      tags:
      - Automation
components:
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical
        request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: ssm
  schemas:
    Alarm:
      type: object
      properties:
        Name:
          type: string
          description: The name of your CloudWatch alarm.
      required:
      - Name
    AlarmConfiguration:
      type: object
      properties:
        IgnorePollAlarmFailure:
          type: boolean
          description: When this value is true, your automation or command continues to run in cases where we can’t retrieve
            alarm status information from CloudWatch. In cases where we successfully retrieve an alarm status of OK or INSUFFICIENT_DATA,
            the automation or command continues to run, regardless of this value. Default is false.
        Alarms:
          type: array
          items:
            $ref: '#/components/schemas/Alarm'
          description: The name of the CloudWatch alarm specified in the configuration.
      required:
      - Alarms
    AutomationDefinitionNotFoundException:
      type: object
      properties:
        Message:
          type: string
    InternalServerError:
      type: object
      properties:
        Message:
          type: string
    StartAutomationExecutionRequest:
      type: object
      properties:
        DocumentName:
          type: string
          description: The name of the SSM document to run. This can be a public document or a custom document. To run a shared
            document belonging to another account, specify the document ARN. For more information about how to use shared
            documents, see Sharing SSM documents in the Amazon Web Services Systems Manager User Guide.
        DocumentVersion:
          type: string
          description: The version of the Automation runbook to use for this execution.
        Parameters:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: A key-value map of execution parameters, which match the declared parameters in the Automation runbook.
        ClientToken:
          type: string
          description: User-provided idempotency token. The token must be unique, is case insensitive, enforces the UUID format,
            and can't be reused.
        Mode:
          type: string
          enum:
          - Auto
          - Interactive
          description: 'The execution mode of the automation. Valid modes include the following: Auto and Interactive. The
            default mode is Auto.'
        TargetParameterName:
          type: string
          description: The name of the parameter used as the target resource for the rate-controlled execution. Required if
            you specify targets.
        Targets:
          type: array
          items:
            $ref: '#/components/schemas/Target'
          description: A key-value mapping to target resources. Required if you specify TargetParameterName. If both this
            parameter and the TargetLocation:Targets parameter are supplied, TargetLocation:Targets takes precedence.
        TargetMaps:
          type: array
          items:
            type: object
            additionalProperties:
              type: array
              items:
                type: string
          description: A key-value mapping of document parameters to target resources. Both Targets and TargetMaps can't be
            specified together.
        MaxConcurrency:
          type: string
          description: The maximum number of targets allowed to run this task in parallel. You can specify a number, such
            as 10, or a percentage, such as 10%. The default value is 10. If both this parameter and the TargetLocation:TargetsMaxConcurrency
            are supplied, TargetLocation:TargetsMaxConcurrency takes precedence.
        MaxErrors:
          type: string
          description: The number of errors that are allowed before the system stops running the automation on additional
            targets. You can specify either an absolute number of errors, for example 10, or a percentage of the target set,
            for example 10%. If you specify 3, for example, the system stops running the automation when the fourth error
            is received. If you specify 0, then the system stops running the automation on additional targets after the first
            error result is returned. If you run an automation on 50 resources and set max-errors to 10%, then the system
            stops running the automation on additional targets whe
        TargetLocations:
          type: array
          items:
            $ref: '#/components/schemas/TargetLocation'
          description: A location is a combination of Amazon Web Services Regions and/or Amazon Web Services accounts where
            you want to run the automation. Use this operation to start an automation in multiple Amazon Web Services Regions
            and multiple Amazon Web Services accounts. For more information, see Running automations in multiple Amazon Web
            Services Regions and accounts in the Amazon Web Services Systems Manager User Guide.
        Tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: 'Optional metadata that you assign to a resource. You can specify a maximum of five tags for an automation.
            Tags enable you to categorize a resource in different ways, such as by purpose, owner, or environment. For example,
            you might want to tag an automation to identify an environment or operating system. In this case, you could specify
            the following key-value pairs: Key=environment,Value=test Key=OS,Value=Windows The Array Members maximum value
            is reported as 1000. This number includes capacity reserved for internal operations. When calling the StartAutomationExecution
            action, you can specify'
        AlarmConfiguration:
          $ref: '#/components/schemas/AlarmConfiguration'
        TargetLocationsURL:
          type: string
          description: Specify a publicly accessible URL for a file that contains the TargetLocations body. Currently, only
            files in presigned Amazon S3 buckets are supported.
      required:
      - DocumentName
    StartAutomationExecutionResult:
      type: object
      properties:
        AutomationExecutionId:
          type: string
          description: The unique ID of a newly scheduled automation execution.
    Tag:
      type: object
      properties:
        Key:
          type: string
          description: The name of the tag.
        Value:
          type: string
          description: The value of the tag.
      required:
      - Key
      - Value
    Target:
      type: object
      properties:
        Key:
          type: string
          description: User-defined criteria for sending commands that target managed nodes that meet the criteria.
        Values:
          type: array
          items:
            type: string
          description: User-defined criteria that maps to Key. For example, if you specified tag:ServerRole, you could specify
            value:WebServer to run a command on instances that include EC2 tags of ServerRole,WebServer. Depending on the
            type of target, the maximum number of values for a key might be lower than the global maximum of 50.
    TargetLocation:
      type: object
      properties:
        Accounts:
          type: array
          items:
            type: string
          description: The Amazon Web Services accounts targeted by the current Automation execution.
        Regions:
          type: array
          items:
            type: string
          description: The Amazon Web Services Regions targeted by the current Automation execution.
        TargetLocationMaxConcurrency:
          type: string
          description: The maximum number of Amazon Web Services Regions and Amazon Web Services accounts allowed to run the
            Automation concurrently. TargetLocationMaxConcurrency has a default value of 1.
        TargetLocationMaxErrors:
          type: string
          description: The maximum number of errors allowed before the system stops queueing additional Automation executions
            for the currently running Automation. TargetLocationMaxErrors has a default value of 0.
        ExecutionRoleName:
          type: string
          description: The Automation execution role used by the currently running Automation. If not specified, the default
            value is AWS-SystemsManager-AutomationExecutionRole.
        TargetLocationAlarmConfiguration:
          $ref: '#/components/schemas/AlarmConfiguration'
        IncludeChildOrganizationUnits:
          type: boolean
          description: Indicates whether to include child organizational units (OUs) that are children of the targeted OUs.
            The default is false.
        ExcludeAccounts:
          type: array
          items:
            type: string
          description: Amazon Web Services accounts or organizational units to exclude as expanded targets.
        Targets:
          type: array
          items:
            $ref: '#/components/schemas/Target'
          description: A list of key-value mappings to target resources. If you specify values for this data type, you must
            also specify a value for TargetParameterName. This Targets parameter takes precedence over the StartAutomationExecution:Targets
            parameter if both are supplied.
        TargetsMaxConcurrency:
          type: string
          description: The maximum number of targets allowed to run this task in parallel. This TargetsMaxConcurrency takes
            precedence over the StartAutomationExecution:MaxConcurrency parameter if both are supplied.
        TargetsMaxErrors:
          type: string
          description: The maximum number of errors that are allowed before the system stops running the automation on additional
            targets. This TargetsMaxErrors parameter takes precedence over the StartAutomationExecution:MaxErrors parameter
            if both are supplied.
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/ssm/service/2014-11-06/ssm-2014-11-06.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)