canonical: https://jentic.com/apis/amazonaws.com/wellarchitected # AWS Well-Architected Tool Jentic publishes the only available OpenAPI specification for AWS Well-Architected Tool, keeping it validated and agent-ready. The AWS Well-Architected Tool API gives programmatic access to the AWS Well-Architected Framework: workloads, lenses, lens reviews, answers, milestones, and improvement plans. Teams use it to assess architectures against the six pillars (operational excellence, security, reliability, performance efficiency, cost optimisation, sustainability), share lenses across accounts, and track remediation progress over time. The 43 operations cover REST-style routes for workloads (/workloads), lenses (/lenses), and the answers, milestones, and reports that hang off them. ## For AI agents Create and manage AWS Well-Architected workloads, run lens reviews, record answers, and pull improvement plans so an agent can drive a recurring architecture review programme. ## Scope Does not handle infrastructure provisioning, automated remediation, or runtime metric collection - use for managing Well-Architected workloads, lens reviews, milestones, and improvement plans only. ## Capabilities - Define workloads with environment, regions, industry, and architectural intent - Associate the AWS Well-Architected Lens or imported custom lenses with a workload - Record and update answers to lens questions, including selected choices and notes - Snapshot a workload's review state into milestones for trend tracking - List per-pillar improvement plans and their priority - Share workloads and custom lenses with other AWS accounts - Export and import custom lens definitions for reuse ## Use cases ### Recurring Architecture Reviews Operate a quarterly Well-Architected review programme by creating a workload per system, associating relevant lenses, walking each pillar's questions to update answers, and snapping a milestone at the end of the quarter. ListLensReviewImprovements then surfaces the priority improvement items per pillar that feed the team's next sprint backlog. Example prompt: Call CreateWorkload with WorkloadName, Environment 'PRODUCTION', AwsRegions, Lenses ['wellarchitected'], then UpdateAnswer for each QuestionId in the security pillar, then CreateMilestone with MilestoneName 'Q2-2026-baseline'. ### Custom Lens Distribution Build a private custom lens that codifies your organisation's internal standards (compliance, deployment hygiene, naming) and distribute it across business units. ImportLens uploads the JSON definition; CreateLensVersion publishes a new version; CreateLensShare grants another AWS account access. ListLensShares shows existing recipients, and ExportLens lets recipients pull the definition for offline review. Example prompt: Call ImportLens with JSONString set to the custom lens definition, then CreateLensVersion with the LensAlias and LensVersion '1.0', then CreateLensShare with SharedWith set to the recipient AWS account ID. ### Consolidated Posture Reporting Generate a consolidated PDF or JSON report across all reviewed workloads using GetConsolidatedReport. Combined with ListWorkloads and GetLensReviewReport per workload, this produces a portfolio-level snapshot of architectural risk: open high-priority items, distribution of risks per pillar, and trend across milestones - useful input for cloud-centre-of-excellence dashboards. Example prompt: Call GetConsolidatedReport with Format 'JSON' and IncludeSharedResources=true, and return the per-workload risk counts. ### Agent-Driven Review Walkthroughs via Jentic An agent that interviews engineers about their system can record their answers directly into the Well-Architected Tool through Jentic. The agent submits an intent like 'update the answer for question OPS01 with a partial-yes selection'; Jentic loads UpdateAnswer with the right path parameters (WorkloadId, LensAlias, QuestionId), executes it, and returns the updated answer object. Keys never leave the vault. Example prompt: Through Jentic, search for 'update an answer in an aws well architected review', load UpdateAnswer, execute with WorkloadId, LensAlias, QuestionId, SelectedChoices, and Notes. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /workloads | Create a workload | | GET | /workloads/{WorkloadId} | Get a workload | | PATCH | /workloads/{WorkloadId}/lensReviews/{LensAlias}/answers/{QuestionId} | Update an answer to a lens question | | POST | /workloads/{WorkloadId}/milestones | Snap a workload milestone | | GET | /consolidatedReport#Format | Get a consolidated report | | PUT | /importLens | Import a custom lens definition | ## Key resources - **Workloads** — /workloads CRUD, ListWorkloads, CreateMilestone, GetWorkload - **Lens reviews** — /workloads/{id}/lensReviews/{lens} for review state, GetLensReview, UpdateLensReview, ListAnswers, UpdateAnswer - **Lenses** — ImportLens, CreateLensVersion, CreateLensShare, ExportLens, GetLens, GetLensVersionDifference - **Reports** — GetLensReviewReport, GetConsolidatedReport - **Improvements** — ListLensReviewImprovements, ListCheckDetails, ListCheckSummaries ## Why Jentic - **Setup:** Wiring AWS Well-Architected Tool by hand means computing SigV4 signatures on every request and picking the right regional wellarchitected host yourself. Through Jentic you install once, import the Well-Architected Tool from the API Directory, store the access keys once, and your agent calls it. - **Permission scoping:** The Well-Architected Tool puts the workload id in the URL path (/workloads/{WorkloadId}/...), so a rule can pin your agent to one workload: it can read the review and update answers for that workload and nothing else. You choose the operations it may call, so a workload delete is not included unless you add it. - **Credential handling:** Your AWS access keys are stored once, encrypted, by your own Jentic One instance and used to sign each Well-Architected Tool request with SigV4 at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'update an answer in a Well-Architected review' or 'create a milestone', and Jentic returns the matching Well-Architected Tool operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **AWS Support** — Trusted Advisor checks (in AWS Support) feed into Well-Architected lens questions for evidence. - **AWS CloudTrail** — CloudTrail provides the API audit history that Well-Architected security questions ask about. - **Amazon CloudWatch** — CloudWatch supplies the operational metrics that justify reliability and performance answers. ## FAQ ### Why is there no official OpenAPI spec for AWS Well-Architected Tool? AWS does not publish an OpenAPI specification for AWS Well-Architected Tool; it ships Smithy models and language-specific SDKs instead. Jentic generates and maintains this OpenAPI spec so that AI agents and developers can call AWS Well-Architected Tool via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the AWS Well-Architected Tool API use? It uses AWS SigV4 in the Authorization header. The IAM principal needs wellarchitected:* permissions on the relevant workload and lens ARNs. Through Jentic, your AWS keys are vaulted and Jentic computes the SigV4 signature for each request. ### Can I run a Well-Architected review entirely through the API? Yes. Call CreateWorkload to create the workload, the lens is associated automatically (or via AssociateLenses), then walk each question with UpdateAnswer to set SelectedChoices and Notes. CreateMilestone snapshots the state for trend tracking. ### What are the rate limits for the Well-Architected Tool? The service has modest management-API throughput suited to interactive use: a few transactions per second per account for read operations and lower for mutations. Throttling responses include the standard ThrottlingException and should be retried with exponential back-off. ### How do I update a Well-Architected answer through Jentic? Search Jentic with 'update an answer in an aws well architected review', load UpdateAnswer (PATCH /workloads/{WorkloadId}/lensReviews/{LensAlias}/answers/{QuestionId}), and execute with the path parameters and a body containing SelectedChoices and Notes. ### Can I import a custom lens from a JSON file? Yes. PUT /importLens accepts a JSONString containing a lens definition; the response returns a LensArn. Then call CreateLensVersion to publish a version and CreateLensShare to share with other AWS accounts. ### Does the Well-Architected Tool integrate with Trusted Advisor? Yes. ListCheckDetails and ListCheckSummaries surface Trusted Advisor checks tied to specific Well-Architected questions, helping reviewers see live evidence (e.g. open security-group issues) alongside the architectural answers. ### Can I limit what my agent is allowed to do with the AWS Well-Architected Tool API? Yes. Jentic One runs self-hosted, so your own rules decide which operations and credentials the agent may use. Because the Well-Architected Tool puts the workload id in the URL path (/workloads/{WorkloadId}/...), a rule can pin the agent to a single workload, letting it read the lens review and call UpdateAnswer or CreateMilestone for that workload and nothing else. You choose which operations are in scope, so a workload delete stays out of reach unless you explicitly add it.