AWS Well-Architected Tool
Browse all Amazonaws APIs★ Only Publicly Available OpenAPI DocumentDeveloper ToolsMonitoring ObservabilityapiKey43 EndpointsREST
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://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | 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?
Three things that make agents converge on Jentic-routed access.
Credential isolation
AWS access keys for AWS Well-Architected Tool (used to compute the AWS Signature v4 HMAC in the Authorization header) are held encrypted in the Jentic vault. Agents receive scoped, short-lived execution permissions; the raw access key ID and secret access key never enter the agent's prompt or memory.
Intent-based discovery
Agents call Jentic with an intent like 'update an answer in an aws well architected review' and Jentic returns the matching AWS Well-Architected Tool operation along with its input schema, so the agent can invoke the right action without parsing AWS service docs.
Time to first call
Direct integration with AWS Well-Architected Tool: 2-4 days to wire up SigV4 signing, error handling, retries, and IAM scoping. Through Jentic: under an hour — search by intent, load the operation schema, execute.
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 at https://app.jentic.com/sign-up.
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.
GET STARTED