canonical: https://jentic.com/apis/amazonaws.com/amazon-elasticsearch-service

# AWS Amazon Elasticsearch Service

Jentic publishes the only available OpenAPI specification for Amazon Elasticsearch Service, keeping it validated and agent-ready. The Amazon Elasticsearch (now OpenSearch) Configuration API creates and manages Elasticsearch domains, including instance configuration, storage, VPC settings, access policies, package associations, and cross-cluster connection setup. The API also covers service software updates, package management, and VPC endpoint authorisation. It is built for platform teams that need to provision and operate search and analytics clusters on AWS without console-driven workflows.

## For AI agents

Provision and manage Amazon Elasticsearch (OpenSearch) domains, packages, and cross-cluster connections through a single API.

## Scope

Does not handle index operations, search queries, or document ingestion - use for Elasticsearch and OpenSearch domain configuration only.

## Capabilities

- Create Elasticsearch and OpenSearch domains with custom instance counts, storage, and VPC settings
- Manage service software updates and cancel pending update windows
- Associate and dissociate packages such as custom dictionaries with running domains
- Set up cross-cluster search by creating inbound and outbound connections between domains
- Authorize and revoke VPC endpoint access for cross-account domain consumers
- Tag and untag domains, packages, and connections for cost allocation
- Describe domain change progress to monitor configuration roll-outs

## Use cases

### Search Domain Provisioning

Platform teams use the Amazon Elasticsearch API to provision search and log-analytics domains with VPC isolation, dedicated master nodes, and EBS storage. The API drives domain creation, configuration updates, and access policy management so that infrastructure pipelines can stand up search backends without console clicks. A typical three-node VPC domain provisions in fifteen to thirty minutes, returning a domain endpoint for application connection.

Example prompt: Create an Elasticsearch domain named search-prod with three r5.large.elasticsearch instances and 100 GiB of EBS storage in subnets subnet-a and subnet-b.

### Cross-Cluster Search Setup

Data platform teams use cross-cluster connections to query indices that live in separate Elasticsearch domains, often for tenancy or region isolation. The API creates inbound and outbound connections, enabling federated queries without bulk data movement. This pattern keeps shard counts manageable per domain while preserving a single query surface for analysts.

Example prompt: Create an outbound cross-cluster connection from domain search-prod to remote domain search-eu and accept the matching inbound connection.

### Service Software Update Coordination

Reliability teams use the API to monitor and time service software updates for Elasticsearch domains so that planned maintenance windows align with low-traffic periods. The API exposes start, schedule, and cancel actions for software updates and surfaces the engine version progress field so dashboards can track fleet-wide patch state. Coordinated updates limit availability impact on customer-facing search.

Example prompt: Cancel the pending service software update on domain search-prod and reschedule it for the next maintenance window.

### Agent-Driven Search Cluster Operations via Jentic

AI agents use the Amazon Elasticsearch API through Jentic to manage domain lifecycle, package associations, and software updates as part of larger platform workflows. Jentic exposes Elasticsearch operations as discoverable tools so an agent can search by intent and execute the matching call. This lets a platform agent respond to capacity or version events without console interaction.

Example prompt: Search Jentic for create elasticsearch domain, load the CreateElasticsearchDomain schema, and execute it for a new staging domain with two t3.medium.elasticsearch nodes.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /2015-01-01/es/domain | Create a new Elasticsearch domain |
| POST | /2015-01-01/packages | Create a custom package such as a synonym list |
| POST | /2015-01-01/packages/associate/{PackageID}/{DomainName} | Associate a package with a domain |
| POST | /2015-01-01/es/domain/{DomainName}/authorizeVpcEndpointAccess | Authorize VPC endpoint access |
| POST | /2015-01-01/es/serviceSoftwareUpdate/cancel | Cancel a pending service software update |
| POST | /2015-01-01/es/ccs/outboundConnection | Create an outbound cross-cluster connection |
| POST | /2015-01-01/tags | Add tags to a domain or package |

## Key resources

- **Domains** — Create, configure, and delete Elasticsearch and OpenSearch domains
- **Packages** — Manage custom dictionaries and synonyms attached to domains
- **Cross-Cluster Connections** — Inbound and outbound connections between domains
- **VPC Endpoints** — Authorize and manage VPC endpoint access to domains
- **Service Software Updates** — Schedule and cancel domain software updates

## Why Jentic

- **Setup:** Wiring the Amazon Elasticsearch Service configuration API by hand means building SigV4 request signing, resolving the regional es.{region}.amazonaws.com host, and handling AWS throttling and retries yourself. Through Jentic you install once, import Elasticsearch Service from the API Directory, store the AWS access keys once, and your agent calls it.
- **Permission scoping:** Elasticsearch Service puts the domain name in the URL path (/2015-01-01/es/domain/{DomainName}/...), so a rule can pin your agent to one domain: it can configure and authorize access for that domain and nothing else. You choose the operations it may call, so domain deletion is not included unless you add it.
- **Credential handling:** Your AWS access keys for the Elasticsearch Service configuration API are stored once, encrypted, by your own Jentic One instance and injected at execution time when the request is signed. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a search domain' or 'associate a package with a domain', and Jentic returns the matching Elasticsearch Service operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Amazon EC2** — Manages the VPC subnets and security groups domains run inside
- **Amazon Kinesis Data Analytics** — Streams data into Elasticsearch domains in near real time
- **AWS Lambda** — Custom indexing and processing functions in front of Elasticsearch

## FAQ

### Why is there no official OpenAPI spec for Amazon Elasticsearch Service?

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

The Configuration API uses AWS Signature Version 4 request signing. Through Jentic, AWS access keys are stored encrypted in the vault and signing happens server-side, so the agent never sees the raw secret access key.

### Can I create OpenSearch domains with this API?

Yes. POST /2015-01-01/es/domain creates Elasticsearch and OpenSearch domains; the EngineVersion field accepts both Elasticsearch_7.x and OpenSearch_x.y values to select the engine.

### What are the rate limits for the Amazon Elasticsearch API?

AWS applies per-account, per-region throttling on the Configuration API. Mutating calls such as CreateElasticsearchDomain are throttled more aggressively than describe calls. Use exponential backoff on ThrottlingException responses; AWS does not publish exact TPS numbers in the spec.

### How do I associate a custom synonyms package with a domain through Jentic?

Search Jentic for associate elasticsearch package, load the schema for POST /2015-01-01/packages/associate/{PackageID}/{DomainName}, and execute it with the package ID and domain name. Jentic returns the association status.

### Does this API run search queries against indices?

No. This is the configuration API for managing domains. Index and search requests go to the per-domain endpoint URL using the standard Elasticsearch or OpenSearch query DSL.

### Can I limit what my agent is allowed to do with the Amazon Elasticsearch Service API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use. Since the domain name sits in the URL path (/2015-01-01/es/domain/{DomainName}/...), you can pin the agent to a single domain so it configures and authorizes access for that domain and nothing else. You also choose which calls it may make, so destructive operations like domain deletion stay off the list unless you add them.