canonical: https://jentic.com/apis/amazonaws.com/amazon-lex-models-v2

# AWS Amazon Lex Model Building V2

Jentic publishes the only available OpenAPI specification for Amazon Lex Model Building V2, keeping it validated and agent-ready. Lex Model Building V2 is the authoring control plane for Amazon Lex conversational bots - it manages bots, bot versions, locales, intents, slot types, slots, custom vocabulary and aliases, and orchestrates the build, import, export and tagging of those resources. The 71 endpoints cover the full bot lifecycle from CreateBot through BuildBotLocale, intent and slot configuration, custom vocabulary upload, version pinning and alias-based deployment.

## For AI agents

Author and version Amazon Lex chatbots end-to-end - create bots, configure intents and slots, train locales, manage custom vocabulary, and publish via aliases.

## Scope

Does not handle runtime conversation, speech recognition inference, or message delivery - use for authoring, training, versioning, and tagging Lex V2 bots only.

## Capabilities

- Create and configure Amazon Lex V2 bots, including locales, intents, slots, slot types, and custom vocabulary entries
- Build a bot locale to compile its NLU model and make it ready for runtime serving
- Manage bot versions and aliases so a chat client can be pinned to a specific tested release
- Import and export bot configurations as ZIP archives for source control or cross-account promotion
- Batch create, update, and delete custom vocabulary items to bias the NLU toward domain-specific terms
- Tag bots, aliases, and other Lex resources for cost allocation and access control
- List, describe, and delete legacy export and import jobs to keep the bot authoring environment tidy

## Use cases

### Author and Version a Conversational Bot End-to-End

Conversational AI teams need to define bots in code rather than the console. Lex Model Building V2 exposes the full authoring lifecycle as API calls - CreateBot, CreateBotLocale, CreateIntent, CreateSlotType, CreateSlot, BuildBotLocale and CreateBotVersion - so an agent can scaffold an entire conversational flow, train it, and pin a runtime alias to a tested version, all without touching the AWS console.

Example prompt: Call POST /bots/ with a bot name and IAM role, then POST /bots/{botId}/botversions/{botVersion}/botlocales/ with localeId=en_US, then POST a BuildBotLocale request and poll until status=Built

### Promote Bots Between Environments via Import and Export

Promoting a Lex bot from development to staging to production benefits from a deterministic artefact rather than re-running create calls. The V2 model API supports CreateExport and CreateImport flows that package an entire bot definition as a ZIP archive, including locales, intents, slot types and custom vocabulary, and unpack it into a different account or region with role-scoped IAM credentials.

Example prompt: Call CreateExport for a botId+botVersion, poll until ExportStatus=Completed, download the ZIP, and call CreateImport in the target region with the same archive

### Bias NLU Recognition With Domain-Specific Vocabulary

Domain-specific terms (drug names, product SKUs, regional spellings) are commonly mis-transcribed by generic NLU. Lex V2 supports custom vocabulary entries scoped per bot locale. An agent can batch-create or batch-update these entries from a CSV catalogue, rebuild the locale, and publish a new version - improving slot recognition accuracy for vertical use cases without retraining the underlying model.

Example prompt: Call /bots/{botId}/botversions/{botVersion}/botlocales/{localeId}/customvocabulary/DEFAULT/batchcreate with an array of phrases and weights, then trigger BuildBotLocale to apply

### AI Agent Integration for Bot Authoring Pipelines

Through Jentic, an agent can drive the entire Lex V2 model-building flow - create bot, configure locales and intents, build, version and tag - by chaining intent searches against the catalogue. Jentic returns each step's input schema and brokers AWS credentials, so an LLM can stand up or modify a Lex bot from a single user instruction without scripting against boto3.

Example prompt: Resolve the intent 'create a Lex V2 bot' via Jentic search, load the CreateBot schema, and execute it with a bot name, role ARN, and idle session TTL

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /bots/ | Create a new Lex V2 bot |
| POST | /bots/{botId}/botversions/{botVersion}/botlocales/ | Create a locale on a bot version |
| POST | /bots/{botId}/botversions/{botVersion}/botlocales/{localeId}/intents/ | Create an intent in a bot locale |
| POST | /bots/{botId}/botversions/{botVersion}/botlocales/{localeId}/customvocabulary/DEFAULT/batchcreate | Batch-create custom vocabulary items |
| POST | /bots/{botId}/botaliases/ | Create a bot alias pointing at a version |
| POST | /imports/ | Import a bot from a ZIP archive |
| POST | /exports/ | Export a bot version as a ZIP archive |

## Key resources

- **Bots** — Create, describe, list, update, and delete Lex V2 bots
- **Bot Locales** — Manage per-language NLU configurations for a bot version, including build status
- **Intents** — Define the user goals a bot can recognise and the prompts that fulfil them
- **Slots and Slot Types** — Configure the typed parameters that intents collect from users
- **Custom Vocabulary** — Bias NLU recognition toward domain-specific phrases with per-locale vocabulary entries
- **Versions and Aliases** — Pin a runtime client to a tested bot version via aliases
- **Imports and Exports** — Round-trip a bot configuration as a ZIP archive across accounts or regions
- **Tags** — Apply key-value tags to Lex resources for cost allocation and IAM scoping

## Why Jentic

- **Setup:** Wiring Amazon Lex Model Building V2 by hand means implementing Signature Version 4 signing, resolving the regional models-v2-lex host, and threading the bot, version, locale, and intent hierarchy yourself. Through Jentic you install once, import Lex Model Building V2 from the API Directory, store the AWS keys once, and your agent calls it.
- **Permission scoping:** Lex Model Building V2 puts the bot id in the URL path (/bots/{botId}/botversions/{botVersion}/botlocales/{localeId}/...), so a rule can pin your agent to one bot: it can author intents and locales for that bot and nothing else. You choose the operations it may call, so bot deletion is not included unless you add it.
- **Credential handling:** Your AWS access keys are stored once, encrypted, by your own Jentic One instance and each request is signed with Signature Version 4 at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Lex bot intent' or 'build a bot locale', and Jentic returns the matching Lex Model Building V2 operation with its input schema, so the agent calls CreateIntent or BuildBotLocale without browsing the reference docs.

## Related APIs

- **Amazon Lex Model Building (V1)** — The earlier Lex V1 model API has a flatter resource layout but is in maintenance mode
- **Amazon Polly** — Polly synthesises the spoken responses played back by Lex voice bots
- **Amazon Comprehend** — Comprehend provides general-purpose entity, sentiment, and language analysis for free-form text
- **AWS Lambda** — Lambda hosts the fulfilment functions that a Lex bot invokes when an intent completes

## FAQ

### Why is there no official OpenAPI spec for Amazon Lex Model Building V2?

AWS does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Amazon Lex Model Building V2 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 Amazon Lex V2 model API use?

The model-building API is signed with AWS Signature Version 4 using IAM access key/secret pairs. Through Jentic, those AWS credentials sit in your Jentic One instance and are used to sign each request on the agent's behalf so raw keys never enter the agent's context.

### Can I create a complete chatbot through the Lex V2 API?

Yes. The API exposes the full authoring stack - CreateBot, CreateBotLocale, CreateIntent, CreateSlotType, CreateSlot, BuildBotLocale, CreateBotVersion and CreateBotAlias - so an agent can scaffold a bot, train its NLU, and publish a runtime alias entirely through API calls.

### What are the rate limits for the Lex V2 model API?

AWS applies per-account and per-region throttling to the Lex control plane. Build operations are particularly slow and concurrency-limited, so design pipelines to poll DescribeBotLocale until status=Built rather than retrying tightly.

### How do I train a bot locale through Jentic?

Use the Jentic search query 'build a Lex bot locale', load the operation behind /bots/{botId}/botversions/{botVersion}/botlocales/{localeId}/, and execute it with your botId, botVersion and localeId. Then poll DescribeBotLocale via Jentic until botLocaleStatus=Built before publishing a version.

### How do I move a bot from one AWS account to another?

Use the Lex V2 export/import flow. Call CreateExport on the source botVersion, poll until ExportStatus=Completed, download the resulting ZIP, then call CreateImport in the target account with the same archive and a target bot name.

### Can I limit what my agent is allowed to do with the Amazon Lex Model Building V2 API?

Yes. Because you run Jentic One yourself, your own rules decide which Lex V2 operations and AWS credentials the agent may use. Since the bot id lives in the URL path, you can pin the agent to a single bot so it may author intents, locales, and slots for that bot and nothing else. You choose the exact operations it can call, so destructive actions like deleting a bot are excluded unless you explicitly allow them.