Amazon IoT Core Iot Core Command Executions API

openapi: 3.2.0
info:
  title: AWS IoT Command Executions API
  version: '2015-05-28'
  description: Generated from AWS's published Smithy model for AWS IoT. 3 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://iot.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Command Executions
paths:
  /command-executions/{executionId}:
    delete:
      operationId: DeleteCommandExecution
      summary: Delete Command Execution
      description: Delete a command execution. Only command executions that enter a terminal state can be deleted from your account.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteCommandExecutionResponse'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '400':
          description: ThrottlingException; ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteCommandExecutionRequest'
      tags:
      - Command Executions
    get:
      operationId: GetCommandExecution
      summary: Get Command Execution
      description: Gets information about the specific command execution on a single device.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCommandExecutionResponse'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '400':
          description: ThrottlingException; ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetCommandExecutionRequest'
      tags:
      - Command Executions
  /command-executions:
    post:
      operationId: ListCommandExecutions
      summary: List Command Executions
      description: List all command executions. You must provide only the startedTimeFilter or the completedTimeFilter information. If you provide both time filters, the API will generate an error. You can use this information to retrieve a list of command executions within a specific timeframe. You must provide only the commandArn or the thingArn information depending on whether you want to list executions for a specific command or an IoT thing. If you provide both fields, the API will generate an error. For more information about considerations for using this API, see List command executions in your account (CLI).
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCommandExecutionsResponse'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '400':
          description: ThrottlingException; ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListCommandExecutionsRequest'
      tags:
      - Command Executions
components:
  schemas:
    GetCommandExecutionRequest:
      type: object
      properties:
        executionId:
          type: string
          description: The unique identifier for the command execution. This information is returned as a response of the StartCommandExecution API request.
        targetArn:
          type: string
          description: The Amazon Resource Number (ARN) of the device on which the command execution is being performed.
        includeResult:
          type: boolean
          description: Can be used to specify whether to include the result of the command execution in the GetCommandExecution API response. Your device can use this field to provide additional information about the command execution. You only need to specify this field when using the AWS-IoT namespace.
      required:
      - executionId
      - targetArn
    TimeFilter:
      type: object
      properties:
        after:
          type: string
          description: Filter to display command executions that started or completed only after a particular date and time.
        before:
          type: string
          description: Filter to display command executions that started or completed only before a particular date and time.
    ResourceNotFoundException:
      type: object
      properties:
        message:
          type: string
          description: The message for the exception.
    DeleteCommandExecutionRequest:
      type: object
      properties:
        executionId:
          type: string
          description: The unique identifier of the command execution that you want to delete from your account.
        targetArn:
          type: string
          description: The Amazon Resource Number (ARN) of the target device for which you want to delete command executions.
      required:
      - executionId
      - targetArn
    ListCommandExecutionsResponse:
      type: object
      properties:
        commandExecutions:
          type: array
          items:
            $ref: '#/components/schemas/CommandExecutionSummary'
          description: The list of command executions.
        nextToken:
          type: string
          description: The token to use to get the next set of results, or null if there are no additional results.
    ConflictException:
      type: object
      properties:
        message:
          type: string
        resourceId:
          type: string
          description: A resource with the same name already exists.
    CommandExecutionResult:
      type: object
      properties:
        S:
          type: string
          description: 'An attribute of type String. For example: "S": "Hello"'
        B:
          type: boolean
          description: 'An attribute of type Boolean. For example: "BOOL": true'
        BIN:
          type: string
          format: byte
          description: An attribute of type Binary.
    CommandParameterValue:
      type: object
      properties:
        S:
          type: string
          description: 'An attribute of type String. For example: "S": "Hello"'
        B:
          type: boolean
          description: 'An attribute of type Boolean. For example: "BOOL": true'
        I:
          type: integer
          description: An attribute of type Integer (Thirty-Two Bits).
        L:
          type: integer
          description: An attribute of type Long.
        D:
          type: number
          description: An attribute of type Double (Sixty-Four Bits).
        BIN:
          type: string
          format: byte
          description: 'An attribute of type Binary. For example: "B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"'
        UL:
          type: string
          description: An attribute of type unsigned long.
    ListCommandExecutionsRequest:
      type: object
      properties:
        maxResults:
          type: integer
          description: The maximum number of results to return in this operation.
        nextToken:
          type: string
          description: To retrieve the next set of results, the nextToken value from a previous response; otherwise null to receive the first set of results.
        namespace:
          type: string
          enum:
          - AWS-IoT
          - AWS-IoT-FleetWise
          description: The namespace of the command.
        status:
          type: string
          enum:
          - CREATED
          - IN_PROGRESS
          - SUCCEEDED
          - FAILED
          - REJECTED
          - TIMED_OUT
          description: List all command executions for the device that have a particular status. For example, you can filter the list to display only command executions that have failed or timed out.
        sortOrder:
          type: string
          enum:
          - ASCENDING
          - DESCENDING
          description: Specify whether to list the command executions that were created in the ascending or descending order. By default, the API returns all commands in the descending order based on the start time or completion time of the executions, that are determined by the startTimeFilter and completeTimeFilter parameters.
        startedTimeFilter:
          $ref: '#/components/schemas/TimeFilter'
        completedTimeFilter:
          $ref: '#/components/schemas/TimeFilter'
        targetArn:
          type: string
          description: The Amazon Resource Number (ARN) of the target device. You can use this information to list all command executions for a particular device.
        commandArn:
          type: string
          description: The Amazon Resource Number (ARN) of the command. You can use this information to list all command executions for a particular command.
    InternalServerException:
      type: object
      properties:
        message:
          type: string
    StatusReason:
      type: object
      properties:
        reasonCode:
          type: string
          description: A code that provides additional context for the command execution status.
        reasonDescription:
          type: string
          description: A literal string for devices to optionally provide additional information about the reason code for a command execution status.
      required:
      - reasonCode
    CommandExecutionSummary:
      type: object
      properties:
        commandArn:
          type: string
          description: The Amazon Resource Name (ARN) of the command execution.
        executionId:
          type: string
          description: The unique identifier of the command execution.
        targetArn:
          type: string
          description: The Amazon Resource Name (ARN) of the target device for which the command is being executed.
        status:
          type: string
          enum:
          - CREATED
          - IN_PROGRESS
          - SUCCEEDED
          - FAILED
          - REJECTED
          - TIMED_OUT
          description: The status of the command executions.
        createdAt:
          type: string
          format: date-time
          description: The date and time at which the command execution was created for the target device.
        startedAt:
          type: string
          format: date-time
          description: The date and time at which the command started executing on the target device.
        completedAt:
          type: string
          format: date-time
          description: The date and time at which the command completed executing on the target device.
    DeleteCommandExecutionResponse:
      type: object
      properties: {}
    GetCommandExecutionResponse:
      type: object
      properties:
        executionId:
          type: string
          description: The unique identifier of the command execution.
        commandArn:
          type: string
          description: The Amazon Resource Number (ARN) of the command. For example, arn:aws:iot:::command/
        targetArn:
          type: string
          description: The Amazon Resource Number (ARN) of the device on which the command execution is being performed.
        status:
          type: string
          enum:
          - CREATED
          - IN_PROGRESS
          - SUCCEEDED
          - FAILED
          - REJECTED
          - TIMED_OUT
          description: The status of the command execution. After your devices receive the command and start performing the operations specified in the command, it can use the UpdateCommandExecution MQTT API to update the status information.
        statusReason:
          $ref: '#/components/schemas/StatusReason'
        result:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CommandExecutionResult'
          description: The result value for the current state of the command execution. The status provides information about the progress of the command execution. The device can use the result field to share additional details about the execution such as a return value of a remote function call. If you use the AWS-IoT-FleetWise namespace, then this field is not applicable in the API response.
        parameters:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CommandParameterValue'
          description: The list of parameters that the StartCommandExecution API used when performing the command on the device.
        executionTimeoutSeconds:
          type: integer
          description: Specifies the amount of time in seconds that the device can take to finish a command execution. A timer starts when the command execution is created. If the command execution status is not set to another terminal state before the timer expires, it will automatically update to TIMED_OUT.
        createdAt:
          type: string
          format: date-time
          description: The timestamp, when the command execution was created.
        lastUpdatedAt:
          type: string
          format: date-time
          description: The timestamp, when the command execution was last updated.
        startedAt:
          type: string
          format: date-time
          description: The timestamp, when the command execution was started.
        completedAt:
          type: string
          format: date-time
          description: The timestamp, when the command execution was completed.
        timeToLive:
          type: string
          format: date-time
          description: The time to live (TTL) parameter that indicates the duration for which executions will be retained in your account. The default value is six months.
    ThrottlingException:
      type: object
      properties:
        message:
          type: string
          description: The message for the exception.
  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: iot
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/iot/service/2015-05-28/iot-2015-05-28.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)