AWS Well-Architected Tool

(1)

AWS Well-Architected Tool

API Reference

API Version 2020-03-31

(2)

AWS Well-Architected Tool: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome

This is the AWS Well-Architected Tool API Reference. The AWS WA Tool API provides programmatic access to the AWS Well-Architected Tool in the AWS Management Console. For information about the AWS Well-Architected Tool, see the AWS Well-Architected Tool User Guide.

This document was last published on March 6, 2022.

(12)

Actions

The following actions are supported:

• AssociateLenses (p. 4)

• CreateLensShare (p. 6)

• CreateLensVersion (p. 9)

• CreateMilestone (p. 12)

• CreateWorkload (p. 15)

• CreateWorkloadShare (p. 21)

• DeleteLens (p. 24)

• DeleteLensShare (p. 27)

• DeleteWorkload (p. 30)

• DeleteWorkloadShare (p. 32)

• DisassociateLenses (p. 34)

• ExportLens (p. 36)

• GetAnswer (p. 38)

• GetLens (p. 42)

• GetLensReview (p. 44)

• GetLensReviewReport (p. 47)

• GetLensVersionDiﬀerence (p. 50)

• GetMilestone (p. 53)

• GetWorkload (p. 56)

• ImportLens (p. 59)

• ListAnswers (p. 63)

• ListLenses (p. 67)

• ListLensReviewImprovements (p. 70)

• ListLensReviews (p. 74)

• ListLensShares (p. 77)

• ListMilestones (p. 80)

• ListNotiﬁcations (p. 83)

• ListShareInvitations (p. 86)

• ListTagsForResource (p. 89)

• ListWorkloads (p. 91)

• ListWorkloadShares (p. 94)

• TagResource (p. 97)

• UntagResource (p. 99)

• UpdateAnswer (p. 101)

• UpdateLensReview (p. 106)

• UpdateShareInvitation (p. 109)

• UpdateWorkload (p. 112)

• UpdateWorkloadShare (p. 118)

• UpgradeLensReview (p. 121)

(13)

(14)

AssociateLenses

Associate a lens to a workload.

Up to 10 lenses can be associated with a workload in a single API operation. A maximum of 20 lenses can be associated with a workload.

Note Disclaimer

By accessing and/or applying custom lenses created by another AWS user or account, you acknowledge that custom lenses created by other users and shared with you are Third Party Content as deﬁned in the AWS Customer Agreement.

Request Syntax

PATCH /workloads/WorkloadId/associateLenses HTTP/1.1 Content-type: application/json

{

"LensAliases": [ "string" ] }

URI Request Parameters

The request uses the following URI parameters.

WorkloadId (p. 4)

The ID assigned to the workload. This ID is unique within an AWS Region.

Pattern: [0-9a-f]{32}

Required: Yes

Request Body

The request accepts the following data in JSON format.

LensAliases (p. 4)

List of lens aliases to associate or disassociate with a workload. Up to 10 lenses can be speciﬁed.

Identify a lens using its LensSummary:LensAlias (p. 147).

Type: Array of strings

Array Members: Minimum number of 1 item.

Length Constraints: Minimum length of 1. Maximum length of 128.

Required: Yes

Response Syntax

HTTP/1.1 200

(15)

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors (p. 176).

AccessDeniedException

User does not have suﬃcient access to perform this action.

HTTP Status Code: 403 ConﬂictException

The resource already exists.

HTTP Status Code: 409 InternalServerException

There is a problem with the AWS Well-Architected Tool API service.

HTTP Status Code: 500 ResourceNotFoundException

The requested resource was not found.

HTTP Status Code: 404 ThrottlingException

Request was denied due to request throttling.

HTTP Status Code: 429 ValidationException

The user input is not valid.

HTTP Status Code: 400

CreateLensShare

Create a lens share.

The owner of a lens can share it with other AWS accounts and IAM users in the same AWS Region. Shared access to a lens is not removed until the lens invitation is deleted.

NoteDisclaimer

By sharing your custom lenses with other AWS accounts, you acknowledge that AWS will make your custom lenses available to those other accounts. Those other accounts may continue to access and use your shared custom lenses even if you delete the custom lenses from your own AWS account or terminate your AWS account.

Request Syntax

POST /lenses/LensAlias/shares HTTP/1.1 Content-type: application/json

{

"ClientRequestToken": "string", "SharedWith": "string"

}

URI Request Parameters

LensAlias (p. 6)

The alias of the lens, for example, serverless.

Each lens is identiﬁed by its LensSummary:LensAlias (p. 147).

Required: Yes

Request Body

ClientRequestToken (p. 6)

A unique case-sensitive string used to ensure that this request is idempotent (executes only once).

You should not reuse the same token for other requests. If you retry a request with the same client request token and the same parameters after it has completed successfully, the result of the original request is returned.

Important

This token is listed as required, however, if you do not specify it, the AWS SDKs

automatically generate one for you. If you are not using the AWS SDK or the AWS CLI, you must provide this token or the request will fail.

Type: String

(17)

Response Syntax

Required: Yes SharedWith (p. 6)

The AWS account ID or IAM role with which the workload is shared.

Type: String

Required: Yes

Response Syntax

HTTP/1.1 200

Content-type: application/json {

"ShareId": "string"

}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

ShareId (p. 7)

The ID associated with the workload share.

Type: String

Errors

(18)

See Also

HTTP Status Code: 404 ServiceQuotaExceededException

The user has reached their resource quota.

CreateLensVersion

Create a new lens version.

A lens can have up to 100 versions.

After a lens has been imported, create a new lens version to publish it. The owner of a lens can share the lens with other AWS accounts and IAM users in the same AWS Region. Only the owner of a lens can delete it.

Request Syntax

POST /lenses/LensAlias/versions HTTP/1.1 Content-type: application/json

{

"ClientRequestToken": "string", "IsMajorVersion": boolean, "LensVersion": "string"

}

URI Request Parameters

Required: Yes

Request Body

Important

Type: String Required: Yes

(20)

Response Syntax

IsMajorVersion (p. 9)

Set to true if this new major lens version.

Type: Boolean Required: No LensVersion (p. 9)

The version of the lens being created.

Type: String

Required: Yes

Response Syntax

HTTP/1.1 200

"LensArn": "string", "LensVersion": "string"

}

Response Elements

LensArn (p. 10)

The ARN for the lens.

Type: String LensVersion (p. 10)

The version of the lens.

Type: String

Errors

(21)

See Also

ConﬂictException

CreateMilestone

Create a milestone for an existing workload.

Request Syntax

POST /workloads/WorkloadId/milestones HTTP/1.1 Content-type: application/json

{ "ClientRequestToken": "string", "MilestoneName": "string"

}

URI Request Parameters

Required: Yes

Request Body

Important

Type: String Required: Yes MilestoneName (p. 12)

The name of the milestone in a workload.

Milestone names must be unique within a workload.

Type: String

Required: Yes

(23)

Response Syntax

HTTP/1.1 200

Content-type: application/json { "MilestoneNumber": number, "WorkloadId": "string"

}

Response Elements

MilestoneNumber (p. 13) The milestone number.

A workload can have a maximum of 100 milestones.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Type: String

Errors

(24)

See Also

ServiceQuotaExceededException

CreateWorkload

Create a new workload.

The owner of a workload can share the workload with other AWS accounts and IAM users in the same AWS Region. Only the owner of a workload can delete it.

For more information, see Deﬁning a Workload in the AWS Well-Architected Tool User Guide.

Request Syntax

POST /workloads HTTP/1.1 Content-type: application/json { "AccountIds": [ "string" ], "ArchitecturalDesign": "string", "AwsRegions": [ "string" ], "ClientRequestToken": "string", "Description": "string", "Environment": "string", "Industry": "string", "IndustryType": "string", "Lenses": [ "string" ], "NonAwsRegions": [ "string" ], "Notes": "string",

"PillarPriorities": [ "string" ], "ReviewOwner": "string",

"Tags": {

"string" : "string"

},

"WorkloadName": "string"

}

URI Request Parameters

The request does not use any URI parameters.

Request Body

AccountIds (p. 15)

The list of AWS account IDs associated with the workload.

Array Members: Maximum number of 100 items.

Pattern: [0-9]{12}

Required: No

ArchitecturalDesign (p. 15)

The URL of the architectural design for the workload.

Type: String

(26)

Request Body

Length Constraints: Maximum length of 2048.

Required: No AwsRegions (p. 15)

The list of AWS Regions associated with the workload, for example, us-east-2, or ca-central-1.

Required: No

Important

Type: String Required: Yes Description (p. 15)

The description for the workload.

Type: String

Required: Yes Environment (p. 15)

The environment for the workload.

Type: String

Valid Values: PRODUCTION | PREPRODUCTION Required: Yes

Industry (p. 15)

The industry for the workload.

Type: String

Required: No IndustryType (p. 15)

The industry type for the workload.

If speciﬁed, must be one of the following:

(27)

Request Body

• Agriculture

• Automobile

• Defense

• Design and Engineering

• Digital Advertising

• Education

• Environmental Protection

• Financial Services

• Gaming

• General Public Services

• Healthcare

• Hospitality

• InfoTech

• Justice and Public Safety

• Life Sciences

• Manufacturing

• Media & Entertainment

• Mining & Resources

• Oil & Gas

• Power & Utilities

• Professional Services

• Real Estate & Construction

• Retail & Wholesale

• Social Protection

• Telecommunications

• Travel, Transportation & Logistics

• Other Type: String

Required: No Lenses (p. 15)

The list of lenses associated with the workload. Each lens is identiﬁed by its LensSummary:LensAlias (p. 147).

Required: Yes NonAwsRegions (p. 15)

The list of non-AWS Regions associated with the workload.

(28)

Response Syntax

Required: No Notes (p. 15)

The notes associated with the workload.

Type: String

Required: No PillarPriorities (p. 15)

The priorities of the pillars, which are used to order items in the improvement plan. Each pillar is represented by its PillarReviewSummary:PillarId (p. 155).

Required: No ReviewOwner (p. 15)

The review owner of the workload. The name, email address, or identiﬁer for the primary group or individual that owns the workload review process.

Type: String

Required: Yes Tags (p. 15)

The tags to be associated with the workload.

Type: String to string map

Map Entries: Maximum number of 50 items.

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Value Length Constraints: Minimum length of 0. Maximum length of 256.

Required: No WorkloadName (p. 15)

The name of the workload.

The name must be unique within an account within an AWS Region. Spaces and capitalization are ignored when checking for uniqueness.

Type: String

Required: Yes

Response Syntax

HTTP/1.1 200

(29)

Response Elements

Content-type: application/json { "WorkloadArn": "string", "WorkloadId": "string"

}

Response Elements

WorkloadArn (p. 18)

The ARN for the workload.

Type: String WorkloadId (p. 18)

Type: String

Errors

(30)

See Also

CreateWorkloadShare

Create a workload share.

The owner of a workload can share it with other AWS accounts and IAM users in the same AWS Region.

Shared access to a workload is not removed until the workload invitation is deleted.

For more information, see Sharing a Workload in the AWS Well-Architected Tool User Guide.

Request Syntax

POST /workloads/WorkloadId/shares HTTP/1.1 Content-type: application/json

{

"ClientRequestToken": "string", "PermissionType": "string", "SharedWith": "string"

}

URI Request Parameters

Required: Yes

Request Body

Important

Type: String Required: Yes PermissionType (p. 21)

Permission granted on a workload share.

(32)

Response Syntax

Type: String

Valid Values: READONLY | CONTRIBUTOR Required: Yes

SharedWith (p. 21)

The AWS account ID or IAM role with which the workload is shared.

Type: String

Required: Yes

Response Syntax

HTTP/1.1 200

Content-type: application/json { "ShareId": "string",

"WorkloadId": "string"

}

Response Elements

ShareId (p. 22)

Type: String

Errors

(33)

See Also

ConﬂictException

DeleteLens

Delete an existing lens.

Only the owner of a lens can delete it. After the lens is deleted, AWS accounts and IAM users that you shared the lens with can continue to use it, but they will no longer be able to apply it to new workloads.

NoteDisclaimer

Request Syntax

DELETE /lenses/LensAlias?ClientRequestToken=ClientRequestToken&LensStatus=LensStatus HTTP/1.1

URI Request Parameters

Important

Required: Yes LensAlias (p. 24)

Required: Yes LensStatus (p. 24)

The status of the lens to be deleted.

Valid Values: ALL | DRAFT | PUBLISHED Required: Yes

Request Body

The request does not have a request body.

(35)

Response Syntax

HTTP/1.1 200

Response Elements

Errors

DeleteLensShare

Delete a lens share.

After the lens share is deleted, AWS accounts and IAM users that you shared the lens with can continue to use it, but they will no longer be able to apply it to new workloads.

NoteDisclaimer

Request Syntax

DELETE /lenses/LensAlias/shares/ShareId?ClientRequestToken=ClientRequestToken HTTP/1.1

URI Request Parameters

Important

Required: Yes LensAlias (p. 27)

Required: Yes ShareId (p. 27)

Required: Yes

Request Body

(38)

Response Syntax

HTTP/1.1 200

Response Elements

Errors

DeleteWorkload

Delete an existing workload.

Request Syntax

DELETE /workloads/WorkloadId?ClientRequestToken=ClientRequestToken HTTP/1.1

URI Request Parameters

Important

Required: Yes WorkloadId (p. 30)

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Response Elements

Errors

(41)

See Also

DeleteWorkloadShare

Delete a workload share.

Request Syntax

DELETE /workloads/WorkloadId/shares/ShareId?ClientRequestToken=ClientRequestToken HTTP/1.1

URI Request Parameters

Important

Required: Yes ShareId (p. 32)

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Response Elements

(43)

Errors

DisassociateLenses

Disassociate a lens from a workload.

Up to 10 lenses can be disassociated from a workload in a single API operation.

NoteThe AWS Well-Architected Framework lens (wellarchitected) cannot be removed from a workload.

Request Syntax

PATCH /workloads/WorkloadId/disassociateLenses HTTP/1.1 Content-type: application/json

{

"LensAliases": [ "string" ] }

URI Request Parameters

Required: Yes

Request Body

LensAliases (p. 34)

List of lens aliases to associate or disassociate with a workload. Up to 10 lenses can be speciﬁed.

Identify a lens using its LensSummary:LensAlias (p. 147).

Array Members: Minimum number of 1 item.

Required: Yes

Response Syntax

HTTP/1.1 200

(45)

Response Elements

Errors

ExportLens

Export an existing lens.

Lenses are deﬁned in JSON. For more information, see JSON format speciﬁcation in the AWS Well- Architected Tool User Guide. Only the owner of a lens can export it.

NoteDisclaimer

Do not include or gather personal identiﬁable information (PII) of end users or other identiﬁable individuals in or via your custom lenses. If your custom lens or those shared with you and used in your account do include or collect PII you are responsible for: ensuring that the included PII is processed in accordance with applicable law, providing adequate privacy notices, and obtaining necessary consents for processing such data.

Request Syntax

GET /lenses/LensAlias/export?LensVersion=LensVersion HTTP/1.1

URI Request Parameters

Required: Yes LensVersion (p. 36)

The lens version to be exported.

Request Body

Response Syntax

HTTP/1.1 200

Content-type: application/json { "LensJSON": "string"

}

Response Elements

(47)

Errors

LensJSON (p. 36)

The JSON for the lens.

Type: String

Errors

GetAnswer

Get the answer to a speciﬁc question in a workload review.

Request Syntax

GET /workloads/WorkloadId/lensReviews/LensAlias/answers/QuestionId?

MilestoneNumber=MilestoneNumber HTTP/1.1

URI Request Parameters

Required: Yes

QuestionId (p. 38)

The ID of the question.

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

(49)

Response Elements

"Answer": {

"ChoiceAnswers": [ {

"ChoiceId": "string", "Notes": "string", "Reason": "string", "Status": "string"

} ],

"Choices": [ {

"ChoiceId": "string", "Description": "string", "HelpfulResource": { "DisplayText": "string", "Url": "string"

},

"ImprovementPlan": { "DisplayText": "string", "Url": "string"

},

"Title": "string"

} ],

"HelpfulResourceDisplayText": "string", "HelpfulResourceUrl": "string",

"ImprovementPlanUrl": "string", "IsApplicable": boolean, "Notes": "string", "PillarId": "string",

"QuestionDescription": "string", "QuestionId": "string",

"QuestionTitle": "string", "Reason": "string",

"Risk": "string",

"SelectedChoices": [ "string" ] },

"LensAlias": "string", "LensArn": "string", "MilestoneNumber": number, "WorkloadId": "string"

}

Response Elements

Answer (p. 38)

An answer of the question.

Type: Answer (p. 125) object LensAlias (p. 38)

Type: String

(50)

Errors

LensArn (p. 38)

The ARN for the lens.

Type: String

Type: Integer

Type: String

Errors

GetLens

Get an existing lens.

Request Syntax

GET /lenses/LensAlias?LensVersion=LensVersion HTTP/1.1

URI Request Parameters

Required: Yes LensVersion (p. 42)

The lens version to be retrieved.

Request Body

Response Syntax

HTTP/1.1 200

Content-type: application/json { "Lens": {

"Description": "string", "LensArn": "string", "LensVersion": "string", "Name": "string", "Owner": "string",

"ShareInvitationId": "string"

}}

Response Elements

(53)

Errors

Lens (p. 42)

A lens return object.

Type: Lens (p. 139) object

Errors

GetLensReview

Get lens review.

Request Syntax

GET /workloads/WorkloadId/lensReviews/LensAlias?MilestoneNumber=MilestoneNumber HTTP/1.1

URI Request Parameters

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

Content-type: application/json { "LensReview": {

"LensAlias": "string", "LensArn": "string", "LensName": "string", "LensStatus": "string", "LensVersion": "string", "NextToken": "string", "Notes": "string",

(55)

Response Elements

"PillarReviewSummaries": [ {

"Notes": "string", "PillarId": "string", "PillarName": "string", "RiskCounts": { "string" : number }

} ],

"RiskCounts": { "string" : number },

"UpdatedAt": number },

"MilestoneNumber": number, "WorkloadId": "string"

}

Response Elements

LensReview (p. 44)

A lens review of a question.

Type: LensReview (p. 141) object MilestoneNumber (p. 44)

The milestone number.

Type: Integer

Type: String

Errors

(56)

See Also

GetLensReviewReport

Get lens review report.

Request Syntax

GET /workloads/WorkloadId/lensReviews/LensAlias/report?MilestoneNumber=MilestoneNumber HTTP/1.1

URI Request Parameters

Required: Yes

Request Body

Response Syntax

HTTP/1.1 200

"LensReviewReport": { "Base64String": "string", "LensAlias": "string", "LensArn": "string"

},

"MilestoneNumber": number, "WorkloadId": "string"

(58)

Response Elements

}

Response Elements

LensReviewReport (p. 47) A report of a lens review.

Type: LensReviewReport (p. 143) object MilestoneNumber (p. 47)

The milestone number.

Type: Integer

Type: String

AWS Well-Architected Tool

AWS Well-Architected Tool

API Reference

API Version 2020-03-31

AWS Well-Architected Tool: API Reference

Table of Contents

Welcome

Actions

AssociateLenses

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateLensShare

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateLensVersion

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateMilestone

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateWorkload

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

CreateWorkloadShare

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

DeleteLens

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

DeleteLensShare

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also

DeleteWorkload

Request Syntax

URI Request Parameters

Request Body

Response Syntax

Response Elements

Errors

See Also