Amazon Well-Architected Tool Well Architected Tool Generations API

openapi: 3.2.0
info:
  title: AWS Well-Architected Tool Generations API
  version: '2020-03-31'
  description: Generated from AWS's published Smithy model for AWS Well-Architected Tool. 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://wellarchitected.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Generations
paths:
  /api/v1/agent-profiles/{profileArn}/generations/{generationId}:
    get:
      operationId: GetAgentRecommendationGeneration
      summary: Get Agent Recommendation Generation
      description: 'Retrieves information about a recommendation generation process, including its status, progress, and results. Recommendation generation is asynchronous: poll this operation until status reaches a terminal value of COMPLETED (results are ready) or ERROR (see errorDetails). Intermediate values are QUEUED and IN_PROGRESS.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAgentRecommendationGenerationResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetAgentRecommendationGenerationRequest'
      tags:
      - Generations
  /api/v1/agent-profiles/{profileArn}/generations:
    get:
      operationId: ListAgentRecommendationGenerations
      summary: List Agent Recommendation Generations
      description: Lists recommendation generation processes for a specified profile.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentRecommendationGenerationsResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListAgentRecommendationGenerationsRequest'
      tags:
      - Generations
    post:
      operationId: StartAgentRecommendationGeneration
      summary: Start Agent Recommendation Generation
      description: Initiates a new recommendation generation process for the specified optimization profile. This asynchronous operation analyzes your Amazon Web Services resources and generates optimization recommendations based on the configured pillars and scope. Use GetAgentRecommendationGeneration to check status.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartAgentRecommendationGenerationResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '402':
          description: ServiceQuotaExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceQuotaExceededException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartAgentRecommendationGenerationRequest'
      tags:
      - Generations
components:
  schemas:
    StartAgentRecommendationGenerationResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the recommendation generation.
        profileArn:
          type: string
          description: The Amazon Resource Name (ARN) of the profile used for this generation.
        name:
          type: string
          description: The name of the recommendation generation.
        status:
          type: string
          enum:
          - QUEUED
          - IN_PROGRESS
          - COMPLETED
          - ERROR
          description: The current status of the recommendation generation.
        estimatedCompletionTime:
          type: string
          description: The estimated time for the generation to complete.
        createdBy:
          type: string
          description: The identifier of the user or system that started this generation.
        createdAt:
          type: string
          description: The timestamp when the generation was started.
        lastModifiedBy:
          type: string
          description: The identifier of the user or system that last modified this generation.
        lastModifiedAt:
          type: string
          description: The timestamp when the generation was last modified.
      required:
      - id
      - profileArn
      - status
      - createdBy
      - createdAt
    AccessDeniedException:
      type: object
      properties:
        Message:
          type: string
      required:
      - Message
    ErrorDetails:
      type: object
      properties:
        code:
          type: string
          description: The status code identifying the type of error.
        message:
          type: string
          description: A human-readable description of the error.
      required:
      - code
      - message
    ListAgentRecommendationGenerationsRequest:
      type: object
      properties:
        profileArn:
          type: string
          description: The Amazon Resource Name (ARN) of the optimization profile to list generation processes for.
        recommendationType:
          type: string
          enum:
          - RESOURCE
          - ARCHITECTURE
          - APPLICATION
          description: Optional filter by recommendation type.
        maxResults:
          type: integer
          description: The maximum number of generation processes to return in a single response.
        nextToken:
          type: string
          description: A pagination token returned from a previous call to continue retrieving results.
      required:
      - profileArn
    ValidationExceptionField:
      type: object
      properties:
        Name:
          type: string
        Message:
          type: string
      required:
      - Name
      - Message
    AgentRecommendationGenerationSummary:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the recommendation generation.
        profileArn:
          type: string
          description: The Amazon Resource Name (ARN) of the profile used for this generation.
        name:
          type: string
          description: The name of the recommendation generation.
        status:
          type: string
          enum:
          - QUEUED
          - IN_PROGRESS
          - COMPLETED
          - ERROR
          description: The current status of the recommendation generation.
        estimatedCompletionTime:
          type: string
          description: The estimated time for the generation to complete.
        createdBy:
          type: string
          description: The identifier of the user or system that started this generation.
        createdAt:
          type: string
          description: The timestamp when the generation was started.
        lastModifiedBy:
          type: string
          description: The identifier of the user or system that last modified this generation.
        lastModifiedAt:
          type: string
          description: The timestamp when the generation was last modified.
      required:
      - id
      - profileArn
      - status
      - createdBy
      - createdAt
    ConflictException:
      type: object
      properties:
        Message:
          type: string
        ResourceId:
          type: string
        ResourceType:
          type: string
      required:
      - Message
      - ResourceId
      - ResourceType
    ServiceQuotaExceededException:
      type: object
      properties:
        Message:
          type: string
        ResourceId:
          type: string
        ResourceType:
          type: string
        QuotaCode:
          type: string
        ServiceCode:
          type: string
      required:
      - Message
      - QuotaCode
      - ServiceCode
    ResourceNotFoundException:
      type: object
      properties:
        Message:
          type: string
        ResourceId:
          type: string
        ResourceType:
          type: string
      required:
      - Message
      - ResourceId
      - ResourceType
    StartAgentRecommendationGenerationRequest:
      type: object
      properties:
        profileArn:
          type: string
          description: The Amazon Resource Name (ARN) of the optimization profile to use for generating recommendations.
        types:
          type: array
          items:
            type: string
            enum:
            - RESOURCE
            - ARCHITECTURE
            - APPLICATION
          description: The types of recommendations to generate.
        name:
          type: string
          description: An optional name for this generation process to help identify it in lists and logs.
        additionalContext:
          type: object
          description: Optional additional context to guide the recommendation generation, such as specific business requirements or constraints.
        scope:
          $ref: '#/components/schemas/Scope'
      required:
      - profileArn
      - types
      - scope
    GetAgentRecommendationGenerationResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the recommendation generation.
        profileArn:
          type: string
          description: The Amazon Resource Name (ARN) of the profile used for this generation.
        name:
          type: string
          description: The name of the recommendation generation.
        status:
          type: string
          enum:
          - QUEUED
          - IN_PROGRESS
          - COMPLETED
          - ERROR
          description: The current status of the recommendation generation.
        estimatedCompletionTime:
          type: string
          description: The estimated time for the generation to complete.
        createdBy:
          type: string
          description: The identifier of the user or system that started this generation.
        createdAt:
          type: string
          description: The timestamp when the generation was started.
        lastModifiedBy:
          type: string
          description: The identifier of the user or system that last modified this generation.
        lastModifiedAt:
          type: string
          description: The timestamp when the generation was last modified.
        additionalContext:
          type: object
          description: Additional context information provided to guide the recommendation generation process.
        scope:
          $ref: '#/components/schemas/Scope'
        startedAt:
          type: string
          description: The timestamp when the recommendation generation process started.
        endedAt:
          type: string
          description: The timestamp when the recommendation generation process completed.
        progress:
          $ref: '#/components/schemas/Progress'
        errorDetails:
          $ref: '#/components/schemas/ErrorDetails'
      required:
      - id
      - profileArn
      - status
      - createdBy
      - createdAt
    ThrottlingException:
      type: object
      properties:
        Message:
          type: string
        QuotaCode:
          type: string
        ServiceCode:
          type: string
      required:
      - Message
    Scope:
      type: object
      properties:
        pillars:
          type: array
          items:
            type: string
            enum:
            - COST_OPTIMIZATION
            - SECURITY
            - RESILIENCE
            - PERFORMANCE
            - OPERATIONAL_EXCELLENCE
          description: The Well-Architected Tool Framework pillars to include in the generation scope.
        goalIds:
          type: array
          items:
            type: string
          description: Specific goal IDs to focus on during recommendation generation.
        items:
          type: array
          items:
            $ref: '#/components/schemas/PillarItem'
          description: Optional per-pillar item filtering configuration.
      required:
      - pillars
    ListAgentRecommendationGenerationsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AgentRecommendationGenerationSummary'
          description: A list of recommendation generation summaries.
        nextToken:
          type: string
          description: A pagination token to retrieve the next set of results, if available.
      required:
      - items
    ValidationException:
      type: object
      properties:
        Message:
          type: string
        Reason:
          type: string
          enum:
          - UNKNOWN_OPERATION
          - CANNOT_PARSE
          - FIELD_VALIDATION_FAILED
          - OTHER
        Fields:
          type: array
          items:
            $ref: '#/components/schemas/ValidationExceptionField'
      required:
      - Message
    PillarItem:
      type: object
      properties:
        pillar:
          type: string
          enum:
          - COST_OPTIMIZATION
          - SECURITY
          - RESILIENCE
          - PERFORMANCE
          - OPERATIONAL_EXCELLENCE
          description: The pillar this item configuration applies to.
        ids:
          type: array
          items:
            type: string
          description: A list of item IDs to process for this pillar, such as best practice IDs, Amazon Web Services service names, or resource ARNs.
      required:
      - pillar
      - ids
    GetAgentRecommendationGenerationRequest:
      type: object
      properties:
        profileArn:
          type: string
          description: The ARN of the optimization profile associated with this generation.
        generationId:
          type: string
          description: The unique identifier of the recommendation generation to retrieve.
      required:
      - profileArn
      - generationId
    InternalServerException:
      type: object
      properties:
        Message:
          type: string
      required:
      - Message
    Progress:
      type: object
      properties:
        stepsCompleted:
          type: integer
          description: The number of generation steps that have been completed.
        totalSteps:
          type: integer
          description: The total number of steps in the generation process.
        completionPercentage:
          type: number
          description: The completion percentage of the generation process (0-100).
      required:
      - stepsCompleted
      - totalSteps
      - completionPercentage
  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: wellarchitected
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/wellarchitected/service/2020-03-31/wellarchitected-2020-03-31.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)