Amazon Well-Architected Tool Well Architected Tool Operations API

openapi: 3.2.0
info:
  title: AWS Well-Architected Tool Operations API
  version: '2020-03-31'
  description: Generated from AWS's published Smithy model for AWS Well-Architected Tool. 8 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: Operations
paths:
  /reviewTemplates/{TemplateArn}/lensReviews/{LensAlias}:
    get:
      operationId: GetReviewTemplateLensReview
      summary: Get Review Template Lens Review
      description: Get a lens review associated with a review template.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetReviewTemplateLensReviewOutput'
        '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/GetReviewTemplateLensReviewInput'
      tags:
      - Operations
    patch:
      operationId: UpdateReviewTemplateLensReview
      summary: Update Review Template Lens Review
      description: Update a lens review associated with a review template.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateReviewTemplateLensReviewOutput'
        '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'
        '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/UpdateReviewTemplateLensReviewInput'
      tags:
      - Operations
  /api/v1/agent-recommendations/{recommendationArn}/items:
    get:
      operationId: ListAgentRecommendationItems
      summary: List Agent Recommendation Items
      description: Lists recommendation items for a specific recommendation. Recommendation items provide detailed information about individual optimization opportunities.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentRecommendationItemsResponse'
        '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/ListAgentRecommendationItemsRequest'
      tags:
      - Operations
  /api/v1/agent-profiles/{profileArn}/recommendations:
    get:
      operationId: ListAgentRecommendations
      summary: List Agent Recommendations
      description: Lists active optimization recommendations for a specified profile with optional filtering by state.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentRecommendationsResponse'
        '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/ListAgentRecommendationsRequest'
      tags:
      - Operations
  /api/v1/agent-recommendations/{recommendationArn}/feedback:
    put:
      operationId: PutAgentRecommendationFeedback
      summary: Put Agent Recommendation Feedback
      description: Submits user feedback on a recommendation to help improve future optimization suggestions and track implementation outcomes.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutAgentRecommendationFeedbackResponse'
        '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/PutAgentRecommendationFeedbackRequest'
      tags:
      - Operations
  /api/v1/agent-recommendations/{recommendationArn}/status:
    patch:
      operationId: UpdateAgentRecommendationStatus
      summary: Update Agent Recommendation Status
      description: Updates the status of a recommendation to track its progress through the implementation lifecycle.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateAgentRecommendationStatusResponse'
        '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/UpdateAgentRecommendationStatusRequest'
      tags:
      - Operations
  /workloads/{WorkloadId}/updateIntegration:
    post:
      operationId: UpdateIntegration
      summary: Update Integration
      description: Update integration features.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: string
        '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'
        '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/UpdateIntegrationInput'
      tags:
      - Operations
  /reviewTemplates/{TemplateArn}/lensReviews/{LensAlias}/upgrade:
    put:
      operationId: UpgradeReviewTemplateLensReview
      summary: Upgrade Review Template Lens Review
      description: Upgrade the lens review of a review template.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: string
        '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'
        '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/UpgradeReviewTemplateLensReviewInput'
      tags:
      - Operations
components:
  schemas:
    UpdateReviewTemplateLensReviewInput:
      type: object
      properties:
        TemplateArn:
          type: string
          description: The review template ARN.
        LensAlias:
          type: string
        LensNotes:
          type: string
        PillarNotes:
          type: object
          additionalProperties:
            type: string
      required:
      - TemplateArn
      - LensAlias
    UpdateReviewTemplateLensReviewOutput:
      type: object
      properties:
        TemplateArn:
          type: string
          description: The review template ARN.
        LensReview:
          $ref: '#/components/schemas/ReviewTemplateLensReview'
    UpdateIntegrationInput:
      type: object
      properties:
        WorkloadId:
          type: string
        ClientRequestToken:
          type: string
        IntegratingService:
          type: string
          enum:
          - JIRA
          description: Which integrated service to update.
      required:
      - WorkloadId
      - ClientRequestToken
      - IntegratingService
    AgentRecommendationSummary:
      type: object
      properties:
        recommendationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recommendation.
        profileArn:
          type: string
          description: The Amazon Resource Name (ARN) of the associated profile.
        generationId:
          type: string
          description: The identifier of the generation process that produced this recommendation.
        title:
          type: string
          description: The title of the recommendation.
        description:
          type: string
          description: A description of the recommendation.
        type:
          type: string
          enum:
          - RESOURCE
          - ARCHITECTURE
          - APPLICATION
          description: The type of the recommendation.
        pillar:
          type: string
          enum:
          - COST_OPTIMIZATION
          - SECURITY
          - RESILIENCE
          - PERFORMANCE
          - OPERATIONAL_EXCELLENCE
          description: The Well-Architected Tool Framework pillar that the recommendation addresses.
        priority:
          type: string
          enum:
          - HIGH
          - MEDIUM
          - LOW
          description: The priority of the recommendation.
        effort:
          type: string
          enum:
          - LARGE
          - MEDIUM
          - SMALL
          description: The effort required to implement the recommendation.
        status:
          type: string
          enum:
          - ACTIVE
          - SUPPRESSED
          - COMPLETED
          description: The current status of the recommendation.
        state:
          type: string
          enum:
          - OPEN
          - CLOSED
          description: The current state of the recommendation.
        updateReason:
          type: string
          description: The free-text reason associated with the recommendation's most recent status update.
        impact:
          type: string
          enum:
          - HIGH
          - MEDIUM
          - LOW
          description: The severity of the recommendation's impact.
        roi:
          $ref: '#/components/schemas/Roi'
        numberOfResources:
          type: integer
          description: The number of Amazon Web Services resources this recommendation affects.
        awsServices:
          type: array
          items:
            type: string
          description: The Amazon Web Services services that the recommendation applies to.
        businessUnits:
          type: array
          items:
            type: string
          description: The business units that own the affected resources.
        applications:
          type: array
          items:
            type: string
          description: The applications that the recommendation targets.
        createdBy:
          type: string
          description: The identifier of the user or system that created this recommendation.
        createdAt:
          type: string
          description: The timestamp when the recommendation was created.
        lastModifiedBy:
          type: string
          description: The identifier of the user or system that last modified this recommendation.
        lastModifiedAt:
          type: string
          description: The timestamp when the recommendation was last modified.
      required:
      - recommendationArn
      - profileArn
      - title
      - description
      - type
      - pillar
      - priority
      - effort
      - status
      - state
      - impact
      - roi
      - createdBy
      - createdAt
    AccessDeniedException:
      type: object
      properties:
        Message:
          type: string
      required:
      - Message
    UpdateAgentRecommendationStatusRequest:
      type: object
      properties:
        recommendationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recommendation to update.
        status:
          type: string
          enum:
          - ACTIVE
          - SUPPRESSED
          - COMPLETED
          description: The new status to assign to the recommendation.
        updateReason:
          type: string
          description: A free-text reason explaining this status update.
      required:
      - recommendationArn
      - status
    ValidationExceptionField:
      type: object
      properties:
        Name:
          type: string
        Message:
          type: string
      required:
      - Name
      - Message
    PutAgentRecommendationFeedbackResponse:
      type: object
      properties: {}
    GetReviewTemplateLensReviewInput:
      type: object
      properties:
        TemplateArn:
          type: string
          description: The review template ARN.
        LensAlias:
          type: string
      required:
      - TemplateArn
      - LensAlias
    GetReviewTemplateLensReviewOutput:
      type: object
      properties:
        TemplateArn:
          type: string
          description: The review template ARN.
        LensReview:
          $ref: '#/components/schemas/ReviewTemplateLensReview'
    ListAgentRecommendationItemsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AgentRecommendationItemSummary'
          description: A list of recommendation items with their detailed metadata and configuration information.
        nextToken:
          type: string
          description: A pagination token to retrieve the next set of results, if available.
      required:
      - items
    ListAgentRecommendationItemsRequest:
      type: object
      properties:
        recommendationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recommendation to list items for.
        type:
          type: string
          enum:
          - AWS_RESOURCE
          - RECOMMENDATION
          description: Optional filter to return only recommendation items of the specified type.
        maxResults:
          type: integer
          description: The maximum number of recommendation items to return in a single response.
        nextToken:
          type: string
          description: A pagination token returned from a previous call to continue retrieving results.
      required:
      - recommendationArn
    ConflictException:
      type: object
      properties:
        Message:
          type: string
        ResourceId:
          type: string
        ResourceType:
          type: string
      required:
      - Message
      - ResourceId
      - ResourceType
    Roi:
      type: object
      properties:
        estimate:
          type: string
          description: A short statistic or key metric. Optional when there is no quantifiable figure.
        detail:
          type: string
          description: A sentence providing context for the estimate.
      required:
      - detail
    UpgradeReviewTemplateLensReviewInput:
      type: object
      properties:
        TemplateArn:
          type: string
          description: The ARN of the review template.
        LensAlias:
          type: string
        ClientRequestToken:
          type: string
      required:
      - TemplateArn
      - LensAlias
    AgentRecommendationItemSummary:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the recommendation item.
        recommendationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the associated recommendation.
        type:
          type: string
          enum:
          - AWS_RESOURCE
          - RECOMMENDATION
          description: The type of the recommendation item.
        metadata:
          type: object
          description: Metadata containing a snapshot of the resource or recommendation at the time of generation.
        createdBy:
          type: string
          description: The identifier of the user or system that created this recommendation item.
        createdAt:
          type: string
          description: The timestamp when the recommendation item was created.
        lastModifiedBy:
          type: string
          description: The identifier of the user or system that last modified this recommendation item.
        lastModifiedAt:
          type: string
          description: The timestamp when the recommendation item was last modified.
      required:
      - id
      - recommendationArn
      - type
      - metadata
      - createdBy
      - createdAt
    ResourceNotFoundException:
      type: object
      properties:
        Message:
          type: string
        ResourceId:
          type: string
        ResourceType:
          type: string
      required:
      - Message
      - ResourceId
      - ResourceType
    ThrottlingException:
      type: object
      properties:
        Message:
          type: string
        QuotaCode:
          type: string
        ServiceCode:
          type: string
      required:
      - Message
    PutAgentRecommendationFeedbackRequest:
      type: object
      properties:
        recommendationArn:
          type: string
          description: The Amazon Resource Name (ARN) of the recommendation to provide feedback for.
        type:
          type: string
          enum:
          - USEFUL
          - NOT_USEFUL
          description: The type of feedback being provided.
        feedbackCategory:
          type: string
          enum:
          - OTHER
          - RECOMMENDATION_NOT_RELEVANT
          - RESOURCE_NOT_IMPORTANT
          - RESOURCE_TYPE_NOT_IMPORTANT
          - RECOMMENDATION_INCORRECT
          description: Optional category classifying the nature of the feedback.
        comments:
          type: string
          description: Optional comments providing additional context about the feedback.
      required:
      - recommendationArn
      - type
    ReviewTemplatePillarReviewSummary:
      type: object
      properties:
        PillarId:
          type: string
        PillarName:
          type: string
        Notes:
          type: string
        QuestionCounts:
          type: object
          additionalProperties:
            type: integer
          description: A count of how many questions are answered and unanswered in the requested pillar of the lens review.
    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
    ListAgentRecommendationsRequest:
      type: object
      properties:
        profileArn:
          type: string
          description: The Amazon Resource Name (ARN) of the optimization profile to list recommendations for.
        maxResults:
          type: integer
          description: The maximum number of recommendations to return in a single response.
        nextToken:
          type: string
          description: A pagination token returned from a previous call to continue retrieving results.
        state:
          type: string
          enum:
          - OPEN
          - CLOSED
          description: Optional filter to return only recommendations with the specified state (OPEN or CLOSED).
        pillar:
          type: string
          enum:
          - COST_OPTIMIZATION
          - SECURITY
          - RESILIENCE
          - PERFORMANCE
          - OPERATIONAL_EXCELLENCE
          description: Optional filter to return only recommendations for the specified pillar.
      required:
      - profileArn
    InternalServerException:
      type: object
      properties:
        Message:
          type: string
      required:
      - Message
    ListAgentRecommendationsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AgentRecommendationSummary'
          description: A list of recommendation summaries.
        nextToken:
          type: string
          description: A pagination token to retrieve the next set of results, if available.
      required:
      - items
    ReviewTemplateLensReview:
      type: object
      properties:
        LensAlias:
          type: string
        LensArn:
          type: string
          description: The lens ARN.
        LensVersion:
          type: string
          description: The version of the lens.
        LensName:
          type: string
        LensStatus:
          type: string
          enum:
          - CURRENT
          - NOT_CURRENT
          - DEPRECATED
          - DELETED
          - UNSHARED
          description: The status of the lens.
        PillarReviewSummaries:
          type: array
          items:
            $ref: '#/components/schemas/ReviewTemplatePillarReviewSummary'
          description: Pillar review summaries of a lens review.
        UpdatedAt:
          type: string
          description: The date and time when the review template lens review was last updated.
        Notes:
          type: string
        QuestionCounts:
          type: object
          additionalProperties:
            type: integer
          description: A count of how many questions are answered and unanswered in the lens review.
        NextToken:
          type: string
    UpdateAgentRecommendationStatusResponse:
      type: object
      properties: {}
  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)