API Reference for Amazon OpenSearch Service - Amazon OpenSearch Service
AuthenticationNew API version and deprecated actionsActionsData typesErrors

API Reference for Amazon OpenSearch Service

Important

This reference was deprecated on September 13, 2022. We will no longer continue to update or maintain this reference. For the most up-to-date documentation of supported OpenSearch Service actions and data types, see the comprehensive 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

Authentication

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.

New API version and deprecated actions

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.

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
DescribeDomainChangeProgress 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": "gp3|gp2|io1|standard",
    "VolumeSize": 10,
    "Iops": 3000,
    "Throughput": 125
  },
  "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

DescribeDomainChangeProgress

Displays status information for a domain configuration change.

Syntax

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

Request parameters

Parameter Data type Required? Description
DomainName DomainName Yes Name of the OpenSearch Service domain.

Request body

Field Data type Required? Description
ChangeId String No The ID of the configuration change. Retrieved from an UpdateDomainConfig request. If not included, OpenSearch Service returns details for the most recent configuration change.

Response elements

Field Data type
ChangeProgressStatus ChangeProgressStatus

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.
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&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&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&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&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.

ListTags

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 only need to specify 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": "gp3|gp2|io1|standard",
    "VolumeSize": 35,
    "Iops": 3000,
    "Throughput": 125
  },
  "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.

ChangeProgressDetails

Container for information about a configuration change happening on a domain.

Field Data type Description
ChangeId String The ID of the configuration change.
Message String A message corresponding to the status of the configuration change.

ChangeProgressStatus

Container for information about the stages of a configuration change happening on a domain.

Field Data type Description
ChangeId String ID of the configuration change.
ChangeProgressStages Object Progress details for each stage of the update process. Each stage includes a Description, LastUpdated, Name, and Status field.
CompletedProperties StringList List of domain properties that have already been updated.
PendingProperties StringList List of domain properties that still need to be updated.
StartTime Timestamp Date and time when the configuration change started.
Status String Current status of the configuration change.
TotalNumberOfStages Integer Total number of stages required for the configuration change to complete.

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.

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 about 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.

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.
ChangeProgressDetails ChangeProgressDetails Container for information about the progress of the configuration change.

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.

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. Options are gp3, gp2, io1, and standard (magnetic).
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 gp3 and provisioned IOPS EBS volume types.
Throughput String Specifies the throughput (in MiB/s) of the EBS volumes attached to data nodes. Applicable only for the gp3 volume 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.

TagList

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.