New API version and deprecated actions Actions Data types Errors

Configuration API reference for Amazon OpenSearch Service

This reference describes the actions, data types, and errors in the Amazon OpenSearch Service configuration API. The configuration API is a REST API that you can use to create and configure OpenSearch Service domains over HTTP. You also can use the AWS CLI and the console to configure OpenSearch Service domains. For more information, see Creating and managing Amazon OpenSearch Service domains.

New API version and deprecated actions
Actions
Data types
Errors

New API version and deprecated actions

Important

The following actions were deprecated in version 2021-01-01 of the Amazon OpenSearch Service API and replaced by more concise and engine-agnostic endpoints. However, the AWS CLI and configuration API continue to accept them.

Deprecated action	Replacement
`AcceptInboundCrossClusterSearchConnection`	`AcceptInboundConnection`
`CreateElasticsearchDomain`	`CreateDomain`
`CreateOutboundCrossClusterSearchConnection`	`CreateOutboundConnection`
`CreateElasticsearchServiceRole`	No replacement. Use the IAM API to create service-linked roles.
`DeleteElasticsearchDomain`	`DeleteDomain`
`DeleteElasticsearchServiceRole`	No replacement. Use the IAM API to delete service-linked roles.
`DeleteInboundCrossClusterSearchConnection`	`DeleteInboundConnection`
`DescribeElasticsearchDomain`	`DescribeDomain`
`DescribeElasticsearchDomainConfig`	`DescribeDomainConfig`
`DescribeElasticsearchInstanceTypeLimits`	`DescribeInstanceTypeLimits`
`DescribeInboundCrossClusterSearchConnections`	`DescribeInboundConnections`
`DescribeOutboundCrossClusterSearchConnections`	`DescribeOutboundConnections`
`DescribeReservedElasticsearchInstanceOfferings`	`DescribeReservedInstanceOfferings`
`DescribeReservedElasticsearchInstances`	`DescribeReservedInstances`
`GetCompatibleElasticsearchVersions`	`GetCompatibleVersions`
`ListElasticsearchInstanceTypeDetails`	`ListInstanceTypeDetails`
`ListElasticsearchVersions`	`ListVersions`
`PurchaseReservedElasticsearchInstanceOffering`	`PurchaseReservedInstanceOffering`
`RejectInboundCrossClusterSearchConnection`	`RejectInboundConnection`
`StartElasticsearchServiceSoftwareUpdate`	`StartServiceSoftwareUpdate`
`StopElasticsearchServiceSoftwareUpdate`	`StopServiceSoftwareUpdate`
`UpdateElasticsearchDomainConfig`	`UpdateDomainConfig`
`UpgradeElasticsearchDomain`	`UpgradeDomain`

Actions

The following table provides a quick reference to the HTTP method required for each operation for the REST interface to the Amazon OpenSearch Service configuration API. The description of each operation also includes the required HTTP method.

Note

All configuration service requests must be signed. For more information, see Signing Amazon OpenSearch Service Requests in this guide and Signature Version 4 Signing Process in the AWS General Reference.

Action	HTTP method
AcceptInboundConnection	`PUT`
AddTags	`POST`
AssociatePackage	`POST`
CancelServiceSoftwareUpdate	`POST`
CreateDomain	`POST`
CreateOutboundConnection	`POST`
CreatePackage	`POST`
DeleteDomain	`DELETE`
DeleteInboundConnection	`DELETE`
DeleteOutboundConnection	`DELETE`
DeletePackage	`DELETE`
DescribeDomainAutoTunes	`GET`
DescribeDomain	`GET`
DescribeDomainConfig	`GET`
DescribeDomains	`POST`
DescribeInstanceTypeLimits	`GET`
DescribeInboundConnections	`POST`
DescribeOutboundConnections	`POST`
DescribePackages	`POST`
DescribeReservedInstanceOfferings	`GET`
DescribeReservedInstances	`GET`
DissociatePackage	`POST`
GetCompatibleVersions	`GET`
GetPackageVersionHistory	`GET`
GetUpgradeHistory	`GET`
GetUpgradeStatus	`GET`
ListDomainNames	`GET`
ListDomainsForPackage	`GET`
ListVersions	`GET`
ListInstanceTypeDetails	`GET`
ListPackagesForDomain	`GET`
ListTags	`GET`
PurchaseReservedInstanceOffering	`POST`
RejectInboundConnection	`PUT`
RemoveTags	`POST`
StartServiceSoftwareUpdate	`POST`
UpdateDomainConfig	`POST`
UpdatePackage	`POST`
UpgradeDomain	`POST`

AcceptInboundConnection

Allows the destination domain owner to accept an inbound cross-cluster search connection request.

Syntax


PUT https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/cc/inboundConnection/connection-id/accept

Request parameters

This operation does not use HTTP request parameters.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`CrossClusterSearchConnection`	Object	Inbound connection details.

AddTags

Attaches resource tags to an OpenSearch Service domain. For more information, see Tagging Amazon OpenSearch Service domains.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/tags
{
  "ARN": "domain-arn",
  "TagList": [{
    "Key": "tag-key",
    "Value": "tag-value"
  }]
}

Request parameters

This operation does not use request parameters.

Request body

Parameter	Data type	Required?	Description
`TagList`	TagList	Yes	List of resource tags.
`ARN`	ARN	Yes	Amazon Resource Name (ARN) for the OpenSearch Service domain to which you want to attach resource tags.

Response elements

The AddTags operation does not return a data structure.

AssociatePackage

Associates a package with an OpenSearch Service domain.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/packages/associate/package-id/domain-name

Request parameters

Parameter	Data type	Required?	Description
`PackageID`	String	Yes	Internal ID of the package that you want to associate with a domain. Use DescribePackages to find this value.
`DomainName`	DomainName	Yes	Name of the domain that you want to associate the package with.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type
`DomainPackageDetails`	DomainPackageDetails

CreateDomain

Creates an OpenSearch Service domain. For more information, see Creating OpenSearch Service domains.

Note

If you attempt to create an OpenSearch Service domain and a domain with the same name already exists, the API does not report an error. Instead, it returns details for the existing domain.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/domain
{
  "ClusterConfig": {
    "ZoneAwarenessConfig": {
      "AvailabilityZoneCount": 3
    },
    "ZoneAwarenessEnabled": true|false,
    "InstanceCount": 3,
    "DedicatedMasterEnabled": true|false,
    "DedicatedMasterType": "c5.large.search",
    "DedicatedMasterCount": 3,
    "InstanceType": "r5.large.search",
    "WarmCount": 3,
    "WarmEnabled": true|false,
    "WarmType": "ultrawarm1.large.search",
    "ColdStorageOptions": {
       "Enabled": true|false
    },
  "EBSOptions": {
    "EBSEnabled": true|false,
    "VolumeType": "io1|gp2|standard",
    "Iops": 1000,
    "VolumeSize": 35
  },
  "EncryptionAtRestOptions": {
    "Enabled": true|false,
    "KmsKeyId":"arn:aws:kms:us-east-1:123456789012:alias/my-key"
  },
  "VPCOptions": {
    "VPCId": "vpc-12345678",
    "SubnetIds": ["subnet-abcdefg1", "subnet-abcdefg2", "subnet-abcdefg3"],
    "SecurityGroupIds": ["sg-12345678"]
  },
  "AdvancedOptions": {
    "rest.action.multi.allow_explicit_index": "true|false",
    "indices.fielddata.cache.size": "40",
    "indices.query.bool.max_clause_count": "1024",
    "override_main_response_version": "true|false"
  },
  "CognitoOptions": {
    "Enabled": true|false,
    "UserPoolId": "us-east-1_121234567",
    "IdentityPoolId": "us-east-1:12345678-1234-1234-1234-123456789012",
    "RoleArn": "arn:aws:iam::123456789012:role/service-role/CognitoAccessForAmazonOpenSearch"
  },
  "NodeToNodeEncryptionOptions": {
    "Enabled": true|false
  },
  "DomainEndpointOptions": {
    "EnforceHTTPS": true|false,
    "TLSSecurityPolicy": "Policy-Min-TLS-1-2-2019-07|Policy-Min-TLS-1-0-2019-07",
    "CustomEndpointEnabled": "true|false",
    "CustomEndpoint": "www.my-custom-endpoint.com",
    "CustomEndpointCertificateArn": "arn:aws:iam::123456789012:certificate/my-certificate"
  },
  "LogPublishingOptions": {
    "SEARCH_SLOW_LOGS": {
      "CloudWatchLogsLogGroupArn":"arn:aws:logs:us-east-1:264071961897:log-group1:sample-domain",
      "Enabled":true|false
    },
    "INDEX_SLOW_LOGS": {
      "CloudWatchLogsLogGroupArn":"arn:aws:logs:us-east-1:264071961897:log-group2:sample-domain",
      "Enabled":true|false
    },
    "ES_APPLICATION_LOGS": {
      "CloudWatchLogsLogGroupArn":"arn:aws:logs:us-east-1:264071961897:log-group3:sample-domain",
      "Enabled":true|false
    }
  },
  "AdvancedSecurityOptions": {
    "Enabled": true|false,
    "InternalUserDatabaseEnabled": true|false,
    "MasterUserOptions": {
      "MasterUserARN": "arn:aws:iam::123456789012:role/my-master-user-role"
      "MasterUserName": "my-master-username",
      "MasterUserPassword": "my-master-password"
    }
  },
  "AutoTuneOptions": {
    "DesiredState": "ENABLED|DISABLED",
    "MaintenanceSchedules": [{
      "StartAt": 1234567890,
      "Duration": {
        "Value": 2,
        "Unit": "HOURS"
      },
      "CronExpressionForRecurrence": "cron(0 0 ? * 3 *)"
    }]
  },
  "TagList": [
    {
      "Key": "stack",
      "Value": "prod"
    }
  ],
  "EngineVersion": "OpenSearch_1.0",
  "DomainName": "my-domain",
  "AccessPolicies": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"AWS\":[\"123456789012\"]},\"Action\":[\"esListDomainNames:ESHttp*\"],\"Resource\":\"arn:aws:es:us-east-1:123456789012:domain/my-domain/*\"}]}"
}

Request parameters

This operation does not use HTTP request parameters.

Request body

Parameter	Data type	Required?	Description
`DomainName`	DomainName	Yes	Name of the OpenSearch Service domain to create.
`EngineVersion`	String	No	Version of OpenSearch or Elasticsearch, in the format Elasticsearch_X.Y or OpenSearch_X.Y. Defaults to the latest version of OpenSearch. For the full list of supported versions, see Supported versions of OpenSearch and Elasticsearch.
`ClusterConfig`	ClusterConfig	No	Container for the cluster configuration of an OpenSearch Service domain.
`EBSOptions`	EBSOptions	No	Container for the parameters required to enable EBS-based storage for an OpenSearch Service domain.
`VPCOptions`	VPCOptions	No	Container for the values required to configure VPC access domains. If you don't specify these values, OpenSearch Service creates the domain with a public endpoint. To learn more, see Launching your Amazon OpenSearch Service domains within a VPC.
`CognitoOptions`	CognitoOptions	No	Key-value pairs to configure OpenSearch Service to use Amazon Cognito authentication for OpenSearch Dashboards.
`AccessPolicies`	String	No	IAM policy document specifying the access policies for the new OpenSearch Service domain. For more information, see Identity and Access Management in Amazon OpenSearch Service.
`SnapshotOptions`	SnapshotOptions	No	DEPRECATED. Container for parameters required to configure automated snapshots of domain indices.
`AdvancedOptions`	AdvancedOptions	No	Key-value pairs to specify advanced configuration options. For more information, see Advanced cluster settings.
`LogPublishingOptions`	LogPublishingOptions	No	Key-value pairs to configure slow log publishing.
`EncryptionAtRestOptions`	EncryptionAtRestOptions	No	Key-value pairs to enable encryption at rest.
`NodeToNodeEncryptionOptions`	NodeToNodeEncryptionOptions	No	Enables node-to-node encryption.
`DomainEndpointOptions`	DomainEndpointOptions	No	Additional options for the domain endpoint, such as whether to require HTTPS for all traffic.
`AdvancedSecurityOptions`	AdvancedSecurityOptions	No	Options for fine-grained access control.
`AutoTuneOptions`	AutoTuneOptions	No	Options for Auto-Tune.
`TagList`	TagList	No	List of tags you want to add to the domain on creation.

Response elements

Field	Data type
`DomainStatus`	DomainStatus

CreateOutboundConnection

Creates a new cross-cluster search connection from a source domain to a destination domain.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/cc/outboundConnection
{
   "ConnectionAlias":"connection-name",
   "LocalDomainInfo":{
      "AWSDomainInformation":{
         "DomainName":"domain-name",
         "Region":"us-east-1"
      }
   },
   "RemoteDomainInfo":{
      "AWSDomainInformation":{
         "OwnerId":"account-id",
         "DomainName":"domain-name",
         "Region":"us-east-1"
      }
   }
}

Request parameters

This operation does not use HTTP request parameters.

Request body

Parameter	Data type	Required?	Description
`ConnectionAlias`	String	Yes	Name of the connection.
`LocalDomainInfo`	Object	Yes	Name and Region of the source domain.
`RemoteDomainInfo`	Object	Yes	Name and Region of the destination domain.

Response elements

Field	Data type	Description
`SourceDomainInfo`	Object	Name and Region of the source domain.
`DestinationDomainInfo`	Object	Name and Region of the destination domain.
`ConnectionAlias`	String	Name of the connection.
`ConnectionStatus`	String	The status of the connection.
`ConnectionId`	String	The ID for the outbound connection.

CreatePackage

Add a package for use with OpenSearch Service domains.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/packages
{
  "PackageName": "my-package-name",
  "PackageType": "TXT-DICTIONARY",
  "PackageDescription": "My synonym file.",
  "PackageSource": {
    "S3BucketName": "my-s3-bucket",
    "S3Key": "synonyms.txt"
  }
}

Request parameters

This operation does not use request parameters.

Request body

Parameter	Data type	Required?	Description
`PackageName`	String	Yes	Unique name for the package.
`PackageType`	String	Yes	Type of package. Currently supports only `TXT-DICTIONARY`.
`PackageDescription`	String	No	Description of the package.
`PackageSource`	PackageSource	Yes	S3 bucket and key for the package.

Response elements

Field	Data type
`PackageDetails`	PackageDetails

CreateElasticsearchServiceRole (Deprecated)

Creates the service-linked role between OpenSearch Service and Amazon EC2. This action is deprecated. OpenSearch Service handles the creation and deletion of service-linked roles automatically.

This role gives OpenSearch Service permissions to place VPC endpoints into your VPC. A service-linked role must be in place for domains with VPC endpoints to be created or function properly.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/role

Request parameters

This operation does not use request parameters.

Request body

This operation does not use the HTTP request body.

Response elements

The CreateServiceRole operation does not return a data structure.

DeleteDomain

Deletes an OpenSearch Service domain and all of its data. You can't recover a domain after it's deleted.

Syntax


DELETE https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/domain/domain-name

Request parameters

Parameter	Data type	Required?	Description
`DomainName`	DomainName	Yes	Name of the OpenSearch Service domain that you want to delete.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type
`DomainStatus`	DomainStatus

DeleteElasticsearchServiceRole (Deprecated)

Deletes the service-linked role between OpenSearch Service and Amazon EC2. This action is deprecated. OpenSearch Service handles the creation and deletion of roles automatically.

This role gives OpenSearch Service permissions to place VPC endpoints into your VPC. A service-linked role must be in place for domains with VPC endpoints to be created or function properly.

Note

This action succeeds only if no domains are using the service-linked role.

Syntax


DELETE https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/role

Request parameters

This operation does not use request parameters.

Request body

This operation does not use the HTTP request body.

Response elements

The DeleteElasticsearchServiceRole operation does not return a data structure.

DeleteInboundConnection

Allows the destination domain owner to delete an existing inbound cross-cluster search connection.

Syntax


DELETE https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/cc/inboundConnection/connection-id

Request parameters

This operation does not use HTTP request parameters.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`CrossClusterSearchConnection`	Object	Inbound connection details.

DeleteOutboundConnection

Allows the source domain owner to delete an existing outbound cross-cluster search connection.

Syntax


DELETE https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/cc/outboundConnection/connection-id

Request parameters

This operation does not use HTTP request parameters.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`CrossClusterSearchConnection`	Object	Outbound connection details.

DeletePackage

Deletes a package from OpenSearch Service. The package can't be associated with any OpenSearch Service domain.

Syntax


DELETE https://es.us-east-1.amazonaws.com/2021-01-01/packages/package-id

Request parameters

Parameter	Data type	Required?	Description
`PackageID`	String	Yes	Internal ID of the package that you want to delete. Use DescribePackages to find this value.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type
`PackageDetails`	PackageDetails

DescribeDomainAutoTunes

Returns the list of optimizations that Auto-Tune has made to the domain.

Syntax


GET https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/domain/domain-name/autoTunes

Request parameters

Parameter	Data type	Required?	Description
`DomainName`	DomainName	Yes	Name of the OpenSearch Service domain that you want Auto-Tune details about.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`AutoTunes`	List	List of optimizations.
`NextToken`	String	Used for pagination. Only necessary if a previous API call produced a result containing `NextToken`. Accepts a next-token input to return results for the next page, and provides a next-token output in the response, which clients can use to retrieve more results.

DescribeDomain

Describes the domain configuration for the specified OpenSearch Service domain, including the domain ID, domain service endpoint, and domain ARN.

Syntax


GET https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/domain/domain-name

Request parameters

Parameter	Data type	Required?	Description
`DomainName`	DomainName	Yes	Name of the OpenSearch Service domain that you want to describe.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type
`DomainStatus`	DomainStatus

DescribeDomainConfig

Displays the configuration of an OpenSearch Service domain.

Syntax


GET https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/domain/domain-name/config

Request parameters

Parameter	Data type	Required?	Description
`DomainName`	DomainName	Yes	Name of the OpenSearch Service domain configuration that you want to describe.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type
`DomainConfig`	DomainConfig

DescribeDomains

Describes the domain configuration for up to five specified OpenSearch Service domains. Information includes the domain ID, domain service endpoint, and domain ARN.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/domain-info
{
  "DomainNames": [
    "domain-name1",
    "domain-name2",
  ]
}

Request parameters

This operation does not use HTTP request parameters.

Request body

Field	Data type	Required?	Description
`DomainNames`	DomainNameList	Yes	Array of OpenSearch Service domain names.

Response elements

Field	Data type
`DomainStatusList`	DomainStatusList

DescribeInstanceTypeLimits

Describes the instance count, storage, and master node limits for a given OpenSearch or Elasticsearch version and instance type.

Syntax


GET https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/instanceTypeLimits/engine-version/instance-type?domainName=domain-name

Request parameters

Parameter	Data type	Required?	Description
`EngineVersion`	String	Yes	Version of OpenSearch or Elasticsearch, in the format Elasticsearch_X.Y or OpenSearch_X.Y. Defaults to the latest version of OpenSearch. For a full list of supported versions, see Supported versions of OpenSearch and Elasticsearch. version. For a list of supported versions, see Supported versions of OpenSearch and Elasticsearch.
`InstanceType`	String	Yes	Instance type. To view instance types by Region, see Amazon OpenSearch Service pricing.
`DomainName`	DomainName	No	The name of an existing domain. Only specify if you need the limits for an existing domain.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`LimitsByRole`	Map	Map that contains all applicable instance type limits. `"data"` refers to data nodes. `"master"` refers to dedicated master nodes.

DescribeInboundConnections

Lists all the inbound cross-cluster search connections for a destination domain.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/cc/inboundConnection/search
{
  "Filters": [
    {
      "Name": filter-name (str),
      "Values" : [val1, val2, ..] (list of strings)
    },
    ....
    "MaxResults": int (Optional, default value - 100), 
    "NextToken": "next-token-string (optional)"
  ]
}

Request parameters

This operation does not use HTTP request parameters.

Request body

Parameter	Data type	Required?	Description
`Filters`	Object	No	List of filter names and values that you can use for the describe requests. The following fields are supported: `connection-id`, `local-domain-info.domain-name`, `local-domain-info.owner-id`, `local-domain-info.region`, and `remote-domain-info.domain-name`.
`MaxResults`	Integer	No	Limits the number of results. The default is 100.
`NextToken`	String	No	Used for pagination. Only necessary if a previous API call produced a result containing `NextToken`. Accepts a next-token input to return results for the next page, and provides a next-token output in the response, which clients can use to retrieve more results.

Response elements

Field	Data type	Description
`CrossClusterSearchConnections`	Object	List of inbound connections.
`NextToken`	String	Used for pagination. Only necessary if a previous API call produced a result containing `NextToken`. Accepts a next-token input to return results for the next page, and provides a next-token output in the response, which clients can use to retrieve more results.

DescribeOutboundConnections

Lists all outbound cross-cluster search connections for a source domain.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/cc/outboundConnection/search
{
  "Filters": [
    {
      "Name": filter-name (str),
      "Values" : [val1, val2, ..] (list of strings)
    },
    ....
    "MaxResults": int (Optional, default value - 100), 
    "NextToken": "next-token-string (optional)"
  ]
}

Request parameters

This operation does not use HTTP Request parameters.

Request body

Parameter	Data type	Required?	Description
`Filters`	Object	No	List of filter names and values that you can use for the describe requests. The following fields are supported: `connection-id`, `remote-domain-info.domain-name`, `remote-domain-info.owner-id`, `remote-domain-info.region`, and `local-domain-info.domain-name`
`MaxResults`	Integer	No	Limits the number of results. The default is 100.
`NextToken`	String	No	Used for pagination. Only necessary if a previous API call produced a result containing `NextToken`. Accepts a next-token input to return results for the next page, and provides a next-token output in the response, which clients can use to retrieve more results.

Response elements

Field	Data type	Description
`CrossClusterSearchConnections`	Object	List of outbound connections.
`NextToken`	String	Used for pagination. Only necessary if a previous API call produced a result containing `NextToken`. Accepts a next-token input to return results for the next page, and provides a next-token output in the response, which clients can use to retrieve more results.

DescribePackages

Describes all packages available to OpenSearch Service. Includes options for filtering, limiting the number of results, and pagination.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/packages/describe
{
  "Filters": [{
    "Name": "PackageStatus",
    "Value": [
      "DELETING", "AVAILABLE"
    ]
  }],
  "MaxResults": 5,
  "NextToken": "next-token",
}

Request parameters

This operation does not use request parameters.

Request body

Parameter	Data type	Required?	Description
`Filters`	Filters	No	Only returns packages that match the provided values.
`MaxResults`	Integer	No	Limits results to a maximum number of packages.
`NextToken`	String	No	Used for pagination. Only necessary if a previous API call includes a non-null `NextToken` value. If provided, returns results for the next page.

Response elements

Field	Data type	Description
`PackageDetailsList`	List	List of PackageDetails objects.

DescribeReservedInstanceOfferings

Describes the available Reserved Instance offerings for a given Region.

Syntax


GET https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/reservedInstanceOfferings?offeringId=offering-id&maxResults=max-results&nextToken=next-token

Request parameters

Parameter	Data type	Required?	Description
`OfferingId`	String	No	The offering ID.
`MaxResults`	Integer	No	Limits the number of results. Must be between 30 and 100.
`NextToken`	String	No	Used for pagination. Only necessary if a previous API call produced a result that contains `NextToken`. Accepts a next-token input to return results for the next page, and provides a next-token output in the response, which clients can use to retrieve more results.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`ReservedInstanceOfferings`	ReservedInstanceOfferings	Container for all information about a Reserved Instance offering. For more information, see Purchasing Reserved Instances (AWS CLI).

DescribeReservedInstances

Describes the instance that you have reserved in a given Region.

Syntax


GET https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/reservedInstances?reservationId=reservation-id&maxResults=max-results&nextToken=next-token

Request parameters

Parameter	Data type	Required?	Description
`ReservationId`	String	No	The reservation ID, assigned after you purchase a reservation.
`MaxResults`	Integer	No	Limits the number of results. Must be between 30 and 100.
`NextToken`	String	No	Used for pagination. Only necessary if a previous API call produced a result that contains `NextToken`. Accepts a next-token input to return results for the next page, and provides a next-token output in the response, which clients can use to retrieve more results.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`ReservedInstances`	ReservedInstances	Container for all information about the instance that you have reserved. For more information, see Purchasing Reserved Instances (AWS CLI).

DissociatePackage

Removes the package from the specified OpenSearch Service domain. The package can't be in use with any OpenSearch index for the dissociation to succeed. The package is still available in OpenSearch Service for association later.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/packages/dissociate/package-id/domain-name

Request parameters

Parameter	Data type	Required?	Description
`PackageID`	String	Yes	Internal ID of the package that you want to dissociate from the domain. Use ListPackagesForDomain to find this value.
`DomainName`	DomainName	Yes	Name of the domain that you want to dissociate the package from.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type
`DomainPackageDetails`	DomainPackageDetails

GetCompatibleVersions

Returns a map of OpenSearch or Elasticsearch versions and the versions you can upgrade them to.

Syntax


GET https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/compatibleVersions?domainName=domain-name

Request parameters

Parameter	Data type	Required?	Description
`DomainName`	DomainName	No	The name of an existing domain.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`CompatibleVersions`	Map	A map of OpenSearch or Elasticsearch versions and the versions you can upgrade them to: `{ "CompatibleVersions": [{ "SourceVersion": "Elasticsearch_7.10", "TargetVersions": ["OpenSearch_1.0"] }] }`

GetPackageVersionHistory

Returns a map of OpenSearch versions and the versions you can upgrade them to.

Syntax


GET https://es.us-east-1.amazonaws.com/2021-01-01/packages/package-id/history?maxResults=max-results&amp;nextToken=next-token

Request parameters

Parameter	Data type	Required?	Description
`PackageID`	String	Yes	The name of an existing domain.
`MaxResults`	Integer	No	Limits the number of results. Must be between 30 and 100.
`NextToken`	String	No	Used for pagination. Only necessary if a previous API call produced a result containing `NextToken`. Accepts a next-token input to return results for the next page, and provides a next-token output in the response, which clients can use to retrieve more results.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`PackageVersionHistoryList`	Map	A list of commit messages, updates tmies, and versions for the given package: `"PackageVersionHistoryList": [ { CommitMessage": "Add new synonyms", "CreatedAt": 1.605225005466E9, "PackageVersion": "v4" } ]`

GetUpgradeHistory

Returns a list of the domain's 10 most-recent upgrade operations.

Syntax


GET https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/upgradeDomain/domain-name/history?maxResults=max-results&amp;nextToken=next-token

Request parameters

Parameter	Data type	Required?	Description
`MaxResults`	Integer	No	Limits the number of results. Must be between 30 and 100.
`DomainName`	DomainName	Yes	The name of an existing domain.
`NextToken`	String	No	Used for pagination. Only necessary if a previous API call produced a result containing `NextToken`. Accepts a next-token input to return results for the next page, and provides a next-token output in the response, which clients can use to retrieve more results.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`UpgradeHistoryList`	UpgradeHistoryList	Container for result logs of the past 10 upgrade operations.

GetUpgradeStatus

Returns the most recent status of a domain's OpenSearch or Elasticsearch version upgrade.

Syntax


GET https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/upgradeDomain/domain-name/status

Request parameters

Parameter	Data type	Required?	Description
`DomainName`	DomainName	Yes	The name of an existing domain.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`UpgradeStepItem`	UpgradeStepItem	Container for the most recent status of a domain's version upgrade.

ListDomainNames

Displays the names of all OpenSearch Service domains owned by the current user in the active Region.

Syntax


GET https://es.us-east-1.amazonaws.com/2021-01-01/domain

Request parameters

Field	Data type	Required?	Description
`EngineType`	String	No	Filters the output by domain engine type. Acceptable values are `Elasticsearch` and `OpenSearch`.

This operation does not use request parameters.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`DomainNameList`	DomainNameList	The names of all OpenSearch Service domains owned by the current user.

ListDomainsForPackage

Lists all OpenSearch Service domains that a package is associated with.

Syntax


GET https://es.us-east-1.amazonaws.com/2021-01-01/packages/package-id/domains?maxResults=max-results&amp;nextToken=next-token

Request parameters

Parameter	Data type	Required?	Description
`PackageID`	String	Yes	The package for which to list domains.
`MaxResults`	Integer	No	Limits the number of results.
`NextToken`	String	No	Used for pagination. Only necessary if a previous API call produced a result that contains `NextToken`. Accepts a next-token input to return results for the next page, and provides a next-token output in the response, which clients can use to retrieve more results.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`DomainPackageDetailsList`	List	List of DomainPackageDetails objects.
`NextToken`	String	Used for pagination. Only necessary if a previous API call produced a result containing `NextToken`. Accepts a next-token input to return results for the next page, and provides a next-token output in the response, which clients can use to retrieve more results.

ListVersions

Lists all supported OpenSearch and Elasticsearch versions on OpenSearch Service.

Syntax


GET https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/versions?maxResults=max-results&nextToken=next-token

Request parameters

Parameter	Data type	Required?	Description
`MaxResults`	Integer	No	Limits the number of results. Must be between 30 and 100.
`NextToken`	String	No	Used for pagination. Only necessary if a previous API call produced a result containing `NextToken`. Accepts a next-token input to return results for the next page, and provides a next-token output in the response, which clients can use to retrieve more results.

Request body

This operation does not use the HTTP request body.

ListInstanceTypeDetails

Lists all instance types and available features for a given OpenSearch or Elasticsearch version.

Syntax


GET https://es.us-east-1.amazonaws.com/2021-01-01/instanceTypeDetails/engine-version?domainName=domain-name?maxResults=max-results&nextToken=next-token

Request parameters

Parameter	Data type	Required?	Description
`EngineVersion`	String	Yes	Version of OpenSearch or Elasticsearch, in the format Elasticsearch_X.Y or OpenSearch_X.Y. Defaults to the latest version of OpenSearch. For the full list of supported versions, see Supported versions of OpenSearch and Elasticsearch.
`DomainName`	DomainName	Yes	Name of the domain that you want to list instance type details for.
`MaxResults`	Integer	No	Limits the number of results. Must be between 30 and 100.
`NextToken`	String	No	Used for pagination. Only necessary if a previous API call produced a result containing `NextToken`. Accepts a next-token input to return results for the next page, and provides a next-token output in the response, which clients can use to retrieve more results.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`InstanceTypeDetails`	List	Lists all supported instance types and features for the given OpenSearch or Elasticsearch version.
`NextToken`	String	Used for pagination. Only necessary if a previous API call produced a result containing `NextToken`. Accepts a next-token input to return results for the next page, and provides a next-token output in the response, which clients can use to retrieve more results.

ListPackagesForDomain

Lists all packages associated with the OpenSearch Service domain.

Syntax


GET https://es.us-east-1.amazonaws.com/2021-01-01/domain/domain-name/packages?maxResults=max-results&amp;nextToken=next-token

Request parameters

Parameter	Data type	Required?	Description
`DomainName`	String	Yes	The name of the domain for which you want to list associated packages.
`MaxResults`	Integer	No	Limits the number of results.
`NextToken`	String	No	Used for pagination. Only necessary if a previous API call produced a result that contains `NextToken`. Accepts a next-token input to return results for the next page, and provides a next-token output in the response, which clients can use to retrieve more results.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`DomainPackageDetailsList`	`List`	List of DomainPackageDetails objects.
`NextToken`	`String`	Used for pagination. Only necessary if a previous API call produced a result containing `NextToken`. Accepts a next-token input to return results for the next page, and provides a next-token output in the response, which clients can use to retrieve more results.

Displays all resource tags for an OpenSearch Service domain.

Syntax


GET https://es.us-east-1.amazonaws.com/2021-01-01/tags?arn=domain-arn

Request parameters

Parameter	Data type	Required?	Description
`ARN`	ARN	Yes	Amazon Resource Name (ARN) for the OpenSearch Service domain.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`TagList`	TagList	List of resource tags. For more information, see Tagging Amazon OpenSearch Service domains.

PurchaseReservedInstanceOffering

Purchases a Reserved Instance.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/purchaseReservedInstanceOffering
{
  "ReservationName" : "my-reservation",
  "ReservedInstanceOfferingId" : "1a2a3a4a5-1a2a-3a4a-5a6a-1a2a3a4a5a6a",
  "InstanceCount" : 3
}

Request parameters

This operation does not use HTTP request parameters.

Request body

Name	Data type	Required?	Description
`ReservationName`	String	Yes	A descriptive name for your reservation. Must be between 5 and 64 characters.
`ReservedInstanceOfferingId`	String	Yes	The offering ID.
`InstanceCount`	Integer	Yes	The number of instances that you want to reserve.

Response elements

Field	Data type	Description
`ReservationName`	String	The name of your reservation.
`ReservedInstanceId`	String	The reservation ID.

RejectInboundConnection

Allows the destination domain owner to reject an inbound cross-cluster search connection request.

Syntax


PUT https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/cc/inboundConnection/connection-id/reject

Request parameters

This operation does not use HTTP request parameters.

Request body

This operation does not use the HTTP request body.

Response elements

Field	Data type	Description
`CrossClusterSearchConnection`	Object	Inbound connection details.

RemoveTags

Removes the specified resource tags from an OpenSearch Service domain.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/tags-removal
{
  "ARN": "arn:aws:es:us-east-1:123456789012:domain/my-domain",
  "TagKeys": [
    "tag-key1",
    "tag-key2"
  ]
}

Request parameters

This operation does not use HTTP request parameters.

Request body

Parameter	Data type	Required?	Description
`ARN`	ARN	Yes	Amazon Resource Name (ARN) of an OpenSearch Service domain. For more information, see IAM identifiers in the AWS Identity and Access Management User Guide.
`TagKeys`	TagKey	Yes	List of tag keys for resource tags that you want to remove from an OpenSearch Service domain.

Response elements

The RemoveTags operation does not return a response element.

StartServiceSoftwareUpdate

Schedules a service software update for an OpenSearch Service domain.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/serviceSoftwareUpdate/start
{
  "DomainName": "domain-name"
}

Request parameters

This operation does not use HTTP request parameters.

Request body

Parameter	Data type	Required?	Description
`DomainName`	DomainName	Yes	Name of the OpenSearch Service domain that you want to update to the latest service software.

Response elements

Field	Data type	Description
`ServiceSoftwareOptions`	`ServiceSoftwareOptions`	Container for the state of your domain relative to the latest service software.

CancelServiceSoftwareUpdate

Stops a scheduled service software update for an OpenSearch Service domain. Only works if the domain's UpdateStatus is PENDING_UPDATE.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/serviceSoftwareUpdate/stop
{
  "DomainName": "domain-name"
}

Request parameters

This operation does not use HTTP request parameters.

Request body

Parameter	Data type	Required?	Description
`DomainName`	DomainName	Yes	Name of the OpenSearch Service domain that you want to update to the latest service software.

Response elements

Field	Data type	Description
`ServiceSoftwareOptions`	ServiceSoftwareOptions	Container for the state of your domain relative to the latest service software.

UpdateDomainConfig

Modifies the configuration of an OpenSearch Service domain, such as the instance type and the number of instances. You need to specify only the values that you want to update.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/domain/domain-name/config
{
  "ClusterConfig": {
    "ZoneAwarenessConfig": {
      "AvailabilityZoneCount": 3
    },
    "ZoneAwarenessEnabled": true|false,
    "InstanceCount": 3,
    "DedicatedMasterEnabled": true|false,
    "DedicatedMasterType": "c5.large.search",
    "DedicatedMasterCount": 3,
    "InstanceType": "r5.large.search",
    "WarmCount": 6,
    "WarmType": "ultrawarm1.medium.search",
    "ColdStorageOptions": {
       "Enabled": true|false
    },
  "EBSOptions": {
    "EBSEnabled": true|false,
    "VolumeType": "io1|gp2|standard",
    "Iops": 1000,
    "VolumeSize": 35
  },
  "SnapshotOptions": {
    "AutomatedSnapshotStartHour": 3
  },
  "EncryptionAtRestOptions": {
    "Enabled": true|false,
    "KmsKeyId":"arn:aws:kms:us-east-1:123456789012:alias/my-key"
  },
  "NodeToNodeEncryptionOptions": {
    "Enabled": true|false
  },
  "VPCOptions": {
    "SubnetIds": ["subnet-abcdefg1", "subnet-abcdefg2", "subnet-abcdefg3"],
    "SecurityGroupIds": ["sg-12345678"]
  },
  "AdvancedOptions": {
    "rest.action.multi.allow_explicit_index": "true|false",
    "indices.fielddata.cache.size": "40",
    "indices.query.bool.max_clause_count": "1024",
    "override_main_response_version": "true|false"
  },
  "CognitoOptions": {
    "Enabled": true|false,
    "UserPoolId": "us-east-1_121234567",
    "IdentityPoolId": "us-east-1:12345678-1234-1234-1234-123456789012",
    "RoleArn": "arn:aws:iam::123456789012:role/service-role/CognitoAccessForAmazonOpenSearch"
  },
  "DomainEndpointOptions": {
    "EnforceHTTPS": true|false,
    "TLSSecurityPolicy": "Policy-Min-TLS-1-2-2019-07|Policy-Min-TLS-1-0-2019-07",
    "CustomEndpointEnabled": "true|false",
    "CustomEndpoint": "www.my-custom-endpoint.com",
    "CustomEndpointCertificateArn": "arn:aws:iam::123456789012:certificate/my-certificate"
  },
  "LogPublishingOptions": {
    "SEARCH_SLOW_LOGS": {
      "CloudWatchLogsLogGroupArn":"arn:aws:logs:us-east-1:264071961897:log-group1:sample-domain",
      "Enabled":true|false
    },
    "INDEX_SLOW_LOGS": {
      "CloudWatchLogsLogGroupArn":"arn:aws:logs:us-east-1:264071961897:log-group2:sample-domain",
      "Enabled":true|false
    },
    "ES_APPLICATION_LOGS": {
      "CloudWatchLogsLogGroupArn":"arn:aws:logs:us-east-1:264071961897:log-group3:sample-domain",
      "Enabled":true|false
    }
  },
  "AdvancedSecurityOptions": {
    "Enabled": true|false,
    "InternalUserDatabaseEnabled": true|false,
    "AnonymousAuthEnabled": true|false,
    "AnonymousAuthDisableDate": 1234567890, 
    "MasterUserOptions": {
      "MasterUserARN": "arn:aws:iam::123456789012:role/my-master-user-role"
      "MasterUserName": "my-master-username",
      "MasterUserPassword": "my-master-password"
    },
    "SAMLOptions": {
      "Enabled": true,
      "Idp": {
        "EntityId": "entity-id",
        "MetadataContent": "metadata-content-with-quotes-escaped"
      },
      "RolesKey": "optional-roles-key",
      "SessionTimeoutMinutes": 180,
      "SubjectKey": "optional-subject-key"
    }
  },
  "AutoTuneOptions": {
    "DesiredState": "ENABLED|DISABLED",
    "MaintenanceSchedules": [{
      "StartAt": 1234567890,
      "Duration": {
        "Value": 2,
        "Unit": "HOURS"
      },
      "CronExpressionForRecurrence": "cron(0 0 ? * 3 *)"
    }],
    "RollbackOnDisable": "NO_ROLLBACK|DEFAULT_ROLLBACK"
  },
  "DomainName": "my-domain",
  "AccessPolicies": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"AWS\":[\"*\"]},\"Action\":[\"es:*\"],\"Resource\":\"arn:aws:es:us-east-1:123456789012:domain/my-domain/*\"}]}",
  "DryRun": true|false
}

Request parameters

This operation does not use HTTP request parameters.

Request body

Parameter	Data type	Required?	Description
`DomainName`	DomainName	Yes	Name of the OpenSearch Service domain for which you want to update the configuration.
`ClusterConfig`	ClusterConfig	No	Changes that you want to make to the cluster configuration, such as the instance type and number of EC2 instances.
`EBSOptions`	EBSOptions	No	Type and size of EBS volumes attached to data nodes.
`VPCOptions`	VPCOptions	No	Container for the values required to configure OpenSearch Service to work with a VPC. To learn more, see Launching your Amazon OpenSearch Service domains within a VPC.
`SnapshotOptions`	SnapshotOptions	No	DEPRECATED. Hour during which the service takes an automated daily snapshot of the indices in the OpenSearch Service domain.
`AdvancedOptions`	AdvancedOptions	No	Key-value pairs to specify advanced configuration options. For more information, see Advanced cluster settings.
`AccessPolicies`	String	No	Specifies the access policies for the OpenSearch Service domain. For more information, see Configuring access policies.
`LogPublishingOptions`	LogPublishingOptions	No	Key-value string pairs to configure slow log publishing.
`CognitoOptions`	CognitoOptions	No	Key-value pairs to configure OpenSearch Service to use Amazon Cognito authentication for OpenSearch Dashboards.
`DomainEndpointOptions`	DomainEndpointOptions	No	Additional options for the domain endpoint, such as whether to require HTTPS for all traffic.
`AdvancedSecurityOptions`	AdvancedSecurityOptions	No	Options for fine-grained access control.
`AutoTuneOptions`	AutoTuneOptions	No	Options for Auto-Tune.
`NodeToNodeEncryptionOptions`	NodeToNodeEncryptionOptions	No	Enables node-to-node encryption.
`EncryptionAtRestOptions`	EncryptionAtRestOptions	No	Key-value pairs to enable encryption at rest.
`DryRun`	Boolean	No	Defaults to `false`. If `true`, OpenSearch Service checks whether the configuration change will cause a blue/green deployment, but does not perform the update.

Response elements

Field	Data type
`DomainConfig`	DomainConfig
`DryRunResults`	DryRunResults

UpdatePackage

Update a package for use with OpenSearch Service domains.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/packages/update
{
  "PackageID": "F11111111",
  "PackageDescription": "My synonym file.",
  "CommitMessage": "Added some synonyms.",
  "PackageSource": {
    "S3BucketName": "my-s3-bucket",
    "S3Key": "synonyms.txt"
  }
}

Request parameters

This operation does not use request parameters.

Request body

Parameter	Data type	Required?	Description
`PackageID`	String	Yes	Unique ID for the package.
`PackageDescription`	String	No	Description of the package.
`CommitMessage`	String	No	Commit message for the updated file.
`PackageSource`	PackageSource	Yes	S3 bucket and key for the package.

Response elements

Field	Data type
`PackageDetails`	PackageDetails

UpgradeDomain

Upgrades an OpenSearch Service domain to a new version of OpenSearch or Elasticsearch. Alternately, checks upgrade eligibility.

Syntax


POST https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/upgradeDomain
{
  "DomainName": "domain-name",
  "TargetVersion": "OpenSearch_1.0",
  "PerformCheckOnly": true|false
}

Request parameters

This operation does not use HTTP request parameters.

Request body

Parameter	Data type	Required?	Description
`DomainName`	String	Yes	Name of the OpenSearch Service domain that you want to upgrade.
`TargetVersion`	String	Yes	OpenSearch or Elasticsearch version to which you want to upgrade, in the format Opensearch_X.Y or Elasticsearch_X.Y. See GetCompatibleVersions.
`PerformCheckOnly`	Boolean	No	Defaults to `false`. If `true`, OpenSearch Service checks the eligibility of the domain, but does not perform the upgrade.
`AdvancedOptions`	AdvancedOptions	No	Only supports the `override_main_response_version` parameter and not other advanced options. You can only include this option when upgrading to an OpenSearch version. Specifies whether the domain reports its version as 7.10 so that it continues to work with Elasticsearch OSS clients and plugins.

Response elements

Field	Data type	Description
`UpgradeDomainResponse`	Map	Basic response confirming operation details.

Data types

This section describes the data types used by the configuration API.

AdvancedOptions

Key-value pairs to specify advanced OpenSearch configuration options.

Field	Data type	Description
`rest.action.multi.allow_explicit_index`	Key-value pair: `"rest.action.multi.allow_explicit_index":"true"`	Note the use of a string rather than a boolean. Specifies whether explicit references to indices are allowed inside the body of HTTP requests. If you want to configure access policies for domain sub-resources, such as specific indices and domain APIs, you must disable this property. For more information about access policies for sub-resources, see Configuring access policies.
`indices.fielddata.cache.size`	Key-value pair: `"indices.fielddata.cache.size":"80"`	Note the use of a string rather than an integer. Specifies the percentage of Java heap space that is allocated to field data. By default, this setting is unbounded.
`indices.query.bool.max_clause_count`	Key-value pair: `"indices.query.bool.max_clause_count":"1024"`	Note the use of a string rather than an integer. Specifies the maximum number of clauses allowed in a Lucene boolean query. 1,024 is the default. Queries with more than the permitted number of clauses that result in a `TooManyClauses` error. To learn more, see the Lucene documentation.
`override_main_response_version`	Key-value pair: `"override_main_response_version":"true"`	Note the use of a string rather than a boolean. Specifies whether the domain reports its version as 7.10 to allow Elasticsearch OSS clients and plugins to continue working with it. Only relevant when creating an OpenSearch domain or upgrading to OpenSearch from an Elasticsearch OSS version. Default is `false` when creating a domain and `true` when upgrading a domain.

AdvancedSecurityOptions

Field	Data type	Description
`Enabled`	Boolean	True to enable fine-grained access control.
`AnonymousAuthEnabled`	Boolean	True to enable a 30-day migration period during which administrators can create role mappings. Only necessary enabling fine-grained access control on an existing domain.
`AnonymousAuthDisableDate`	Timestamp	Date and time when the migration period will be disabled.
`InternalUserDatabaseEnabled`	Boolean	True to enable the internal user database.
`MasterUserOptions`	MasterUserOptions	Container for information about the master user.
`SAMLOptions`	SAMLOptions	Container for information about the SAML configuration for OpenSearch Dashboards.

ARN

Field	Data type	Description
`ARN`	String	Amazon Resource Name (ARN) of an OpenSearch Service domain. For more information, see IAM ARNs in the AWS Identity and Access Management User Guide.

AutoTuneOptions

Field Data type Description

DesiredState String Either ENABLED or DISABLED.

MaintenanceSchedules

List

A list of maintenance schedules during which Auto-Tune can deploy changes:


{
  "StartAt": 1234567890,
  "Duration": {
    "Value": 2,
    "Unit": "HOURS"
  },
  "CronExpressionForRecurrence": "cron(* * ? * * *)"
}

Maintenance schedules are overwrite, not append. If your request includes no schedules, the request deletes all existing schedules. To preserve existing schedules, make a call to DescribeDomainConfig first and use the MaintenanceSchedules portion of the response as the basis for this section.

StartAt is Epoch time, and Value is a long integer.

RollbackOnDisable

String

When disabling Auto-Tune, specify NO_ROLLBACK to retain all prior Auto-Tune settings or DEFAULT_ROLLBACK to revert to the OpenSearch Service defaults.

If you specify DEFAULT_ROLLBACK, you must include a MaintenanceSchedule in the request. Otherwise, OpenSearch Service is unable to perform the rollback.

CognitoOptions

Field	Data type	Description
`Enabled`	Boolean	Whether to enable or disable Amazon Cognito authentication for OpenSearch Dashboards. See Configuring Amazon Cognito authentication for OpenSearch Dashboards.
`UserPoolId`	String	The Amazon Cognito user pool ID that you want OpenSearch Service to use for OpenSearch Dashboards authentication.
`IdentityPoolId`	String	The Amazon Cognito identity pool ID that you want OpenSearch Service to use for OpenSearch Dashboards authentication.
`RoleArn`	String	The `AmazonOpenSearchServiceCognitoAccess` role that allows OpenSearch Service to configure your user pool and identity pool.

ColdStorageOptions

Container for the parameters required to enable cold storage for an OpenSearch Service domain.

Field	Data type	Description
`Enabled`	Boolean	Whether to enable or disable cold storage on the domain. See Cold storage for Amazon OpenSearch Service.

CreateDomainRequest

Container for the parameters required by the CreateDomain service operation.

Field	Data type	Description
`DomainName`	DomainName	Name of the OpenSearch Service domain to create.
`ClusterConfig`	ClusterConfig	Container for the cluster configuration of an OpenSearch Service domain.
`EBSOptions`	EBSOptions	Container for the parameters required to enable EBS-based storage for an OpenSearch Service domain.
`AccessPolicies`	String	IAM policy document that specifies the access policies for the new OpenSearch Service domain. For more information, see Configuring access policies.
`DomainEndpointOptions`	DomainEndpointOptions	Additional options for the domain endpoint, such as whether to require HTTPS for all traffic.
`SnapshotOptions`	SnapshotOptions	DEPRECATED. Container for parameters required to configure automated snapshots of domain indices.
`VPCOptions`	VPCOptions	Container for the values required to configure OpenSearch Service to work with a VPC.
`LogPublishingOptions`	LogPublishingOptions	Key-value string pairs to configure slow log publishing.
`AdvancedOptions`	AdvancedOptions	Key-value pairs to specify advanced configuration options.
`CognitoOptions`	CognitoOptions	Key-value pairs to configure OpenSearch Service to use Amazon Cognito authentication for OpenSearch Dashboards.
`NodeToNodeEncryptionOptions`	NodeToNodeEncryptionOptions	Specify `true` to enable node-to-node encryption.

DomainEndpointOptions

Field	Data type	Description
`EnforceHTTPS`	Boolean	`true` to require that all traffic to the domain arrive over HTTPS.
`TLSSecurityPolicy`	String	The minimum TLS version required for traffic to the domain. Valid values are TLS 1.0 (default) or 1.2: `Policy-Min-TLS-1-0-2019-07` `Policy-Min-TLS-1-2-2019-07`
`CustomEndpointEnabled`	Boolean	Whether to enable a custom endpoint for the domain.
`CustomEndpoint`	String	The fully qualified URL for the custom endpoint.
`CustomEndpointCertificateArn`	String	The ARN for your security certificate, managed in ACM.

DomainID

Data type	Description
String	Unique identifier for an OpenSearch Service domain.

DomainName

Name of an OpenSearch Service domain.

Data type	Description
String	Name of an OpenSearch Service domain. Domain names are unique across all domains owned by the same account within an AWS Region. Domain names must start with a lowercase letter and must be between 3 and 28 characters. Valid characters are a-z (lowercase only), 0-9, and – (hyphen).

DomainNameList

String of OpenSearch Service domain names.

Data type	Description
String Array	Array of OpenSearch Service domains in the following format: `["<Domain_Name>","<Domain_Name>"...]`

DomainPackageDetails

Information on a package that is associated with a domain.

Field	Data type	Description
DomainName	String	Name of the domain you associated a package with.
DomainPackageStatus	String	State of the association. Values are `ASSOCIATING`, `ASSOCIATION_FAILED`, `ACTIVE`, `DISSOCIATING`, and `DISSOCIATION_FAILED`.
ErrorDetails	String	Additional information if the package is in an error state. Null otherwise.
LastUpdated	Timestamp	Timestamp of the most-recent update to the association status.
PackageID	String	Internal ID of the package.
PackageName	String	User-specified name of the package.
PackageType	String	Currently supports only `TXT-DICTIONARY`.
ReferencePath	String	Denotes the location of the package on the OpenSearch Service cluster nodes. It's the same as `synonym_path` for dictionary files.

EBSOptions

Container for the parameters required to enable EBS-based storage for an OpenSearch Service domain.

Field	Data type	Description
`EBSEnabled`	Boolean	Indicates whether EBS volumes are attached to data nodes in an OpenSearch Service domain.
`VolumeType`	String	Specifies the type of EBS volumes attached to data nodes.
`VolumeSize`	String	Specifies the size (in GiB) of EBS volumes attached to data nodes.
`Iops`	String	Specifies the baseline input/output (I/O) performance of EBS volumes attached to data nodes. Applicable only for the provisioned IOPS EBS volume type.

ClusterConfig

Container for the cluster configuration of an OpenSearch Service domain.

Field	Data type	Description
`InstanceType`	String	Instance type of data nodes in the cluster.
`InstanceCount`	Integer	Number of instances in the cluster.
`DedicatedMasterEnabled`	Boolean	Indicates whether dedicated master nodes are enabled for the cluster. `True` if the cluster will use a dedicated master node. `False` if the cluster will not. For more information, see Dedicated master nodes in Amazon OpenSearch Service.
`DedicatedMasterType`	String	OpenSearch Service instance type of the dedicated master nodes in the cluster.
`DedicatedMasterCount`	Integer	Number of dedicated master nodes in the cluster. This number must be greater than 1, otherwise you receive a validation exception.
`ZoneAwarenessEnabled`	Boolean	Indicates whether multiple Availability Zones are enabled. For more information, see Configuring a multi-AZ domain in Amazon OpenSearch Service.
`ZoneAwarenessConfig`	ZoneAwarenessConfig	Container for zone awareness configuration options. Only required if `ZoneAwarenessEnabled` is `true`.
`WarmEnabled`	Boolean	Whether to enable warm storage for the cluster.
`WarmCount`	Integer	The number of warm nodes in the cluster.
`WarmType`	String	The instance type for the cluster's warm nodes.
`WarmStorage`	Integer	The total provisioned amount of warm storage in GiB.
`ColdStorageOptions`	ColdStorageOptions	Container for cold storage configuration options.

DomainConfig

Container for the configuration of an OpenSearch Service domain.

Field	Data type	Description
`EngineVersion`	String	OpenSearch or Elasticsearch version.
`ClusterConfig`	ClusterConfig	Container for the cluster configuration of an OpenSearch Service domain.
`EBSOptions`	EBSOptions	Container for EBS options configured for an OpenSearch Service domain.
`AccessPolicies`	String	Specifies the access policies for the OpenSearch Service domain. For more information, see Configuring access policies.
`SnapshotOptions`	SnapshotOptions	DEPRECATED. Container for parameters required to configure automated snapshots of domain indices.
`DomainEndpointOptions`	DomainEndpointOptions	Additional options for the domain endpoint, such as whether to require HTTPS for all traffic.
`VPCOptions`	VPCDerivedInfo	The current VPCOptions for the domain and the status of any updates to their configuration.
`LogPublishingOptions`	LogPublishingOptions	Key-value pairs to configure slow log publishing.
`AdvancedOptions`	AdvancedOptions	Key-value pairs to specify advanced configuration options.
`EncryptionAtRestOptions`	EncryptionAtRestOptions	Key-value pairs to enable encryption at rest.
`NodeToNodeEncryptionOptions`	NodeToNodeEncryptionOptions	Whether node-to-node encryption is enabled or disabled.

DomainStatus

Container for the contents of a DomainStatus data structure.

Field	Data type	Description
`DomainID`	DomainID	Unique identifier for an OpenSearch Service domain.
`DomainName`	DomainName	Name of an OpenSearch Service domain. Domain names are unique across all domains owned by the same account within an AWS Region. Domain names must start with a lowercase letter and must be between 3 and 28 characters. Valid characters are a-z (lowercase only), 0-9, and – (hyphen).
`ARN`	ARN	Amazon Resource Name (ARN) of an OpenSearch Service domain. For more information, see IAM identifiers in the AWS Identity and Access Management User Guide.
`Created`	Boolean	Status of the creation of an OpenSearch Service domain. `True` if creation of the domain is complete. `False` if domain creation is still in progress.
`Deleted`	Boolean	Status of the deletion of an OpenSearch Service domain. `True` if deletion of the domain is complete. `False` if domain deletion is still in progress.
`Endpoint`	ServiceUrl	Domain-specific endpoint used to submit index, search, and data upload requests to an OpenSearch Service domain.
`Endpoints`	EndpointsMap	The key-value pair that exists if the OpenSearch Service domain uses VPC endpoints.
`Processing`	Boolean	Status of a change in the configuration of an OpenSearch Service domain. `True` if the service is still processing the configuration changes. `False` if the configuration change is active. You must wait for a domain to reach active status before submitting index, search, and data upload requests.
`EngineVersion`	String	OpenSearch or Elasticsearch version.
`ClusterConfig`	ClusterConfig	Container for the cluster configuration of an OpenSearch Service domain.
`EBSOptions`	EBSOptions	Container for the parameters required to enable EBS-based storage for an OpenSearch Service domain.
`AccessPolicies`	String	IAM policy document specifying the access policies for the new OpenSearch Service domain. For more information, see Configuring access policies.
`SnapshotOptions`	SnapshotOptions	DEPRECATED. Container for parameters required to configure the time of daily automated snapshots of OpenSearch Service domain indices.
`VPCOptions`	VPCDerivedInfo	Information that OpenSearch Service derives based on VPCOptions for the domain.
`LogPublishingOptions`	LogPublishingOptions	Key-value pairs to configure slow log publishing.
`AdvancedOptions`	AdvancedOptions	Key-value pairs to specify advanced configuration options.
`EncryptionAtRestOptions`	EncryptionAtRestOptions	Key-value pairs to enable encryption at rest.
`CognitoOptions`	CognitoOptions	Key-value pairs to configure OpenSearch Service to use Amazon Cognito authentication for OpenSearch Dashboards.
`NodeToNodeEncryptionOptions`	NodeToNodeEncryptionOptions	Whether node-to-node encryption is enabled or disabled.
`UpgradeProcessing`	Boolean	True if an upgrade to a new OpenSearch or Elasticsearch version is in progress.
`ServiceSoftwareOptions`	ServiceSoftwareOptions	The status of the domain's service software.

DomainStatusList

List that contains the status of each specified OpenSearch Service domain.

Field	Data type	Description
`DomainStatusList`	DomainStatus	List that contains the status of each specified OpenSearch Service domain.

DryRunResults

Results of a dry run performed in an update domain request.

Field	Data type	Description
`DeploymentType`	String	The results of a dry run performed in an UpdateDomainConfig operation. Describes the type of deployment the update will cause. One of four values: Blue/Green DynamicUpdate Undetermined None
`Message`	String	A message corresponding to the deployment type.

EncryptionAtRestOptions

Specifies whether the domain should encrypt data at rest, and if so, the AWS Key Management Service (KMS) key to use. Can be used only to create a new domain, not update an existing one. To learn more, see Enabling encryption of data at rest.

Field	Data type	Description
`Enabled`	Boolean	Specify `true` to enable encryption at rest.
`KmsKeyId`	String	The KMS key ID. Takes the form `1a2a3a4-1a2a-3a4a-5a6a-1a2a3a4a5a6a`.

EndpointsMap

The key-value pair that contains the VPC endpoint. Only exists if the OpenSearch Service domain resides in a VPC.

Field	Data type	Description
`Endpoints`	Key-value string pair: `"vpc": "<VPC_ENDPOINT>"`	The VPC endpoint for the domain.

Filters

Filters the packages included in a DescribePackages response.

Field	Data type	Description
`Name`	String	Any field from PackageDetails.
`Value`	List	A list of values for the specified field.

LogPublishingOptions

Specifies whether the OpenSearch Service domain publishes the OpenSearch application and slow logs to Amazon CloudWatch. You still have to enable the collection of slow logs using the OpenSearch REST API. To learn more, see Setting OpenSearch logging thresholds for slow logs.

Field Data type Description

INDEX_SLOW_LOGS

Key-value

Two key-value pairs that define the CloudWatch log group and whether the OpenSearch index slow log should be published there:


"CloudWatchLogsLogGroupArn":"arn:aws:logs:us-east-1:264071961897:log-group:sample-domain",
"Enabled":true

SEARCH_SLOW_LOGS

Key-value

Two key-value pairs that define the CloudWatch log group and whether the OpenSearch search slow log should be published there:


"CloudWatchLogsLogGroupArn":"arn:aws:logs:us-east-1:264071961897:log-group:sample-domain",
"Enabled":true

ES_APPLICATION_LOGS

Key-value

Two key-value pairs that define the CloudWatch log group and whether the OpenSearch error logs should be published there:


"CloudWatchLogsLogGroupArn":"arn:aws:logs:us-east-1:264071961897:log-group:sample-domain",
"Enabled":true

MasterUserOptions

Field	Data type	Description
`MasterUserARN`	String	ARN for the master user. Only specify if `InternalUserDatabaseEnabled` is `false` in AdvancedSecurityOptions.
`MasterUserName`	String	Username for the master user. Only specify if `InternalUserDatabaseEnabled` is `true` in AdvancedSecurityOptions.
`MasterUserPassword`	String	Password for the master user. Only specify if `InternalUserDatabaseEnabled` is `true` in AdvancedSecurityOptions.

NodeToNodeEncryptionOptions

Enables or disables node-to-node encryption.

Field	Data type	Description
`Enabled`	Boolean	Enable with `true`.

OptionState

State of an update to advanced options for an OpenSearch Service domain.

Field	Data type	Description
`OptionStatus`	String	One of three valid values: RequiresIndexDocuments Processing Active

OptionStatus

Status of an update to configuration options for an OpenSearch Service domain.

Field	Data type	Description
`CreationDate`	Timestamp	Date and time when the OpenSearch Service domain was created.
`UpdateDate`	Timestamp	Date and time when the OpenSearch Service domain was updated.
`UpdateVersion`	Integer	Whole number that specifies the latest version for the entity.
`State`	OptionState	State of an update to configuration options for an OpenSearch Service domain.
`PendingDeletion`	Boolean	Indicates whether the service is processing a request to permanently delete the OpenSearch Service domain and all of its resources.

PackageDetails

Basic information about a package.

Field	Data type	Description
`CreatedAt`	Timestamp	The time the package was created.
`ErrorDetails`	String	Additional information if the package is in an error state. Null otherwise.
`PackageDescription`	String	User-specified description of the package.
`PackageID`	String	Internal ID of the package.
`PackageName`	String	User-specified name of the package.
`PackageStatus`	String	Values are `COPYING`, `COPY_FAILED`, `AVAILABLE`, `DELETING`, or `DELETE_FAILED` .
`PackageType`	String	Currently supports only `TXT-DICTIONARY`.

PackageSource

Bucket and key for the package you want to add to OpenSearch Service.

Field	Data type	Description
`S3BucketName`	String	Name of the bucket containing the package.
`S3Key`	String	Key (file name) of the package.

SAMLOptions

Field	Data type	Description
`Enabled`	Boolean	Whether to enable SAML authentication for OpenSearch Dashboards.
`MasterUserName`	String	This username from the SAML IdP receives full permissions to the cluster, equivalent to a new master user.
`MasterBackendRole`	String	This backend role from the SAML IdP receives full permissions to the cluster, equivalent to a new master user.
`Idp`	Object	Container for information from your identity provider. Contains two elements: `"Idp": { "EntityId": "entity-id", "MetadataContent": "metadata-content-with-quotes-escaped" }`
`RolesKey`	String	Element of the SAML assertion to use for backend roles. Default is `roles`.
`SubjectKey`	String	Element of the SAML assertion to use for username. Default is `NameID`.
`SessionTimeoutMinutes`	Integer	Duration of a session in minutes after a user logs in. Default is 60. Maximum value is 1,440 (24 hours).

ServiceSoftwareOptions

Container for the state of your domain relative to the latest service software.

Field	Data type	Description
`UpdateAvailable`	Boolean	Whether a service software update is available for your domain.
`Cancellable`	Boolean	If you have requested a domain update, whether or not you can cancel the update.
`AutomatedUpdateDate`	Timestamp	The Epoch time that the deployment window closes for required updates. After this time, OpenSearch Service schedules the software upgrade automatically.
`UpdateStatus`	String	The status of the update. Values are `ELIGIBLE`, `PENDING_UPDATE`, `IN_PROGRESS`, `COMPLETED`, and `NOT_ELIGIBLE`.
`Description`	String	More detailed description of the status.
`CurrentVersion`	String	Your current service software version.
`NewVersion`	String	The latest service software version.
`OptionalDeployment`	Boolean	Whether the service software update is optional.

ServiceURL

Domain-specific endpoint used to submit index, search, and data upload requests to an OpenSearch Service domain.

Field	Data type	Description
`ServiceURL`	String	Domain-specific endpoint used to submit index, search, and data upload requests to an OpenSearch Service domain.

SnapshotOptions

DEPRECATED. See Creating index snapshots in Amazon OpenSearch Service. Container for parameters required to configure the time of daily automated snapshots of the indices in an OpenSearch Service domain.

Field	Data type	Description
`AutomatedSnapshotStartHour`	Integer	DEPRECATED. Hour during which the service takes an automated daily snapshot of the indices in the OpenSearch Service domain.

Tag

Field	Data type	Description
`Key`	TagKey	Required name of the tag. Tag keys must be unique for the OpenSearch Service domain to which they are attached. For more information, see Tagging Amazon OpenSearch Service domains.
`Value`	TagValue	Optional string value of the tag. Tag values can be `null` and do not have to be unique in a tag set. For example, you can have a key-value pair in a tag set of project/Trinity and cost-center/Trinity.

TagKey

Field	Data type	Description
`Key`	String	Name of the tag. String can have up to 128 characters.

Field	Data type	Description
`Tag`	Tag	Resource tag attached to an OpenSearch Service domain.

TagValue

Field	Data type	Description
`Value`	String	Holds the value for a `TagKey`. String can have up to 256 characters.

VPCDerivedInfo

Field	Data type	Description
`VPCId`	String	The ID for your VPC. Amazon VPC generates this value when you create a VPC.
`SubnetIds`	StringList	A list of subnet IDs associated with the VPC endpoints for the domain. For more information, see VPCs and subnets in the Amazon VPC User Guide.
`AvailabilityZones`	StringList	The list of Availability Zones associated with the VPC subnets. For more information, see VPC and subnet basics in the Amazon VPC User Guide.
`SecurityGroupIds`	StringList	The list of security group IDs associated with the VPC endpoints for the domain. For more information, see Security groups for your VPC in the Amazon VPC User Guide.

VPCOptions

Field	Data type	Description
`SubnetIds`	StringList	A list of subnet IDs associated with the VPC endpoints for the domain. If your domain uses multiple Availability Zones, you need to provide two subnet IDs, one per zone. Otherwise, provide only one. To learn more, see VPCs and subnets in the Amazon VPC User Guide.
`SecurityGroupIds`	StringList	The list of security group IDs associated with the VPC endpoints for the domain. If you do not provide a security group ID, OpenSearch Service uses the default security group for the VPC. To learn more, see Security groups for your VPC in the Amazon VPC User Guide.
`VPCId`	String	ID for the VPC.

ZoneAwarenessConfig

Field	Data type	Description
`AvailabilityZoneCount`	Integer	If you enabled multiple Availability Zones, this field is the number of zones that you want the domain to use. Valid values are `2` and `3`.

Errors

OpenSearch Service throws the following errors:

Exception	Description
`BaseException`	Thrown for all service errors. Contains the HTTP status code of the error.
`ValidationException`	Thrown when the HTTP request contains invalid input or is missing required input. Returns HTTP status code 400.
`DisabledOperationException`	Thrown when the client attempts to perform an unsupported operation. Returns HTTP status code 409.
`InternalException`	Thrown when an error internal to the service occurs while processing a request. Returns HTTP status code 500.
`InvalidTypeException`	Thrown when trying to create or access an OpenSearch Service domain sub-resource that is either invalid or not supported. Returns HTTP status code 409.
`LimitExceededException`	Thrown when trying to create more than the allowed number and type of OpenSearch Service domain resources and sub-resources. Returns HTTP status code 409.
`ResourceNotFoundException`	Thrown when accessing or deleting a resource that does not exist. Returns HTTP status code 400.
`ResourceAlreadyExistsException`	Thrown when a client attempts to create a resource that already exists in an OpenSearch Service domain. Returns HTTP status code 400.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Troubleshooting

Document history