AWS Well-Architected Tool
Browse all Amazonaws APIsAgent-ready OpenAPI document · curated by JenticDeveloper ToolsMonitoring ObservabilityapiKey43 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For 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.
Use for: Create a new Well-Architected workload for my production system, Associate the AWS Well-Architected Lens with a workload, Update an answer to a Well-Architected question, Generate a milestone snapshot of my workload's current state
Not supported: Does not handle infrastructure provisioning, automated remediation, or runtime metric collection - use for managing Well-Architected workloads, lens reviews, milestones, and improvement plans only.
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.
Install Jentic One Beta
Connect the AWS Well-Architected Tool to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the AWS Well-Architected Tool, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Famazonaws.com%2Fwellarchitected" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Famazonaws.com%2Fwellarchitected" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with AWS Well-Architected Tool API.
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
Patterns agents use AWS Well-Architected Tool API for, with concrete tasks.
★ 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.
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.
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.
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.
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
43 endpoints — jentic publishes the only available openapi specification for aws well-architected tool, keeping it validated and agent-ready.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using AWS Well-Architected Tool API through Jentic.
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.
GET STARTED