Actions

The ballerinax/elastic.elasticcloud package exposes the following clients:

Client	Purpose
`Client`	Provides access to the Elastic Cloud REST API for deployment management, organization admin, traffic filters, extensions, API keys, and more.

Client

Provides access to the Elastic Cloud REST API for deployment management, organization admin, traffic filters, extensions, API keys, and more.

Configuration

Field	Type	Default	Description
`authorization`	`string`	Required	The API key authorization header value (e.g., `"ApiKey " + apiKey`).

Initializing the client

import ballerinax/elastic.elasticcloud;

configurable string apiKey = ?;

elasticcloud:Client elasticClient = check new ({
    authorization: "ApiKey " + apiKey
});

Operations

Account operations

Fetch current account information

Retrieves the current account information including trust settings.

Returns: AccountResponse|error

Sample code:

elasticcloud:AccountResponse account = check elasticClient->/account();

Sample response:

{"id": "abc123456789", "trust": {"trust_all": false}}

Updates the current account

Replaces the current account settings with the provided values.

Parameters:

Name	Type	Required	Description
`payload`	`AccountUpdateRequest`	Yes	The updated account data.

Returns: AccountResponse|error

Sample code:

elasticcloud:AccountResponse updated = check elasticClient->/account.put({});

Sample response:

{"id": "abc123456789", "trust": {"trust_all": true}}

Patch the current account

Applies partial updates to the current account using JSON Merge Patch rules.

Parameters:

Name	Type	Required	Description
`payload`	`string`	Yes	JSON Merge Patch payload for partial account updates.

Returns: AccountResponse|error

Sample code:

elasticcloud:AccountResponse patched = check elasticClient->/account.patch("{}");

Sample response:

{"id": "abc123456789", "trust": {"trust_all": false}}

Deployment operations

List Deployments

Retrieves all deployments belonging to the authenticated user.

Returns: DeploymentsListResponse|error

Sample code:

elasticcloud:DeploymentsListResponse deploymentsList = check elasticClient->/deployments();

Sample response:

{"deployments": [{"id": "a1b2c3d4e5", "name": "my-deployment", "resources": [{"ref_id": "main-elasticsearch", "kind": "elasticsearch", "id": "es-abc123"}]}]}

Create Deployment

Creates a new deployment with the specified configuration.

Parameters:

Name	Type	Required	Description
`payload`	`DeploymentCreateRequest`	Yes	The deployment definition including name, region, and version.
`queries`	`CreateDeploymentQueries`	No	Query parameters including `template_id` and `validate_only`.

Returns: DeploymentCreateResponse|error

Sample code:

elasticcloud:DeploymentCreateResponse createdDeployment = check elasticClient->/deployments.post(
    {
        name: "ballerina-example-deployment",
        region: "gcp-asia-south1",
        version: "8.17.0"
    },
    queries = {template_id: "gcp-general-purpose"}
);

Sample response:

{"id": "f6g7h8i9j0", "name": "ballerina-example-deployment", "created": true, "resources": [{"ref_id": "main-elasticsearch", "kind": "elasticsearch", "id": "es-xyz789"}]}

Search Deployments

Searches for deployments matching a query. When no query is specified, all deployments are matched.

Parameters:

Name	Type	Required	Description
`payload`	`SearchRequest`	Yes	The search query. Use an empty record to match all deployments.
`queries`	`SearchDeploymentsQueries`	No	Query parameters for search pagination.

Returns: DeploymentsSearchResponse|error

Sample code:

elasticcloud:DeploymentsSearchResponse searchResults = check elasticClient->/deployments/_search.post(
    {size: 10}
);

Sample response:

{"return_count": 2, "deployments": [{"id": "a1b2c3d4e5", "name": "my-deployment", "healthy": true}, {"id": "f6g7h8i9j0", "name": "test-deployment", "healthy": true}]}

Get Deployment

Retrieves detailed information about a specific deployment.

Parameters:

Name	Type	Required	Description
`deploymentId`	`string`	Yes	Identifier for the deployment.
`queries`	`GetDeploymentQueries`	No	Query parameters to control response detail.

Returns: DeploymentGetResponse|error

Sample code:

elasticcloud:DeploymentGetResponse deployment = check elasticClient->/deployments/["a1b2c3d4e5"]();

Sample response:

{"id": "a1b2c3d4e5", "name": "my-deployment", "healthy": true, "resources": {"elasticsearch": [], "kibana": [], "apm": [], "integrations_server": [], "enterprise_search": []}}

Update Deployment

Updates an existing deployment with a new configuration.

Parameters:

Name	Type	Required	Description
`deploymentId`	`string`	Yes	Identifier for the deployment.
`payload`	`DeploymentUpdateRequest`	Yes	The updated deployment definition.

Returns: DeploymentUpdateResponse|error

Sample code:

elasticcloud:DeploymentUpdateResponse updated = check elasticClient->/deployments/["a1b2c3d4e5"].put(
    {name: "renamed-deployment"}
);

Sample response:

{"id": "a1b2c3d4e5", "name": "renamed-deployment", "resources": [{"ref_id": "main-elasticsearch", "kind": "elasticsearch", "id": "es-abc123"}]}

Shuts down Deployment

Shuts down all resources in a deployment.

Parameters:

Name	Type	Required	Description
`deploymentId`	`string`	Yes	Identifier for the deployment.
`queries`	`ShutdownDeploymentQueries`	No	Query parameters including `hide` and `skip_snapshot`.

Returns: DeploymentShutdownResponse|error

Sample code:

elasticcloud:DeploymentShutdownResponse shutdownResp = check elasticClient->/deployments/["a1b2c3d4e5"]/_shutdown.post();

Sample response:

{"id": "a1b2c3d4e5", "name": "my-deployment"}

Restores a shutdown Deployment

Restores a previously shut-down deployment.

Parameters:

Name	Type	Required	Description
`deploymentId`	`string`	Yes	Identifier for the deployment.

Returns: DeploymentRestoreResponse|error

Sample code:

elasticcloud:DeploymentRestoreResponse restoreResp = check elasticClient->/deployments/["a1b2c3d4e5"]/_restore.post();

Sample response:

{"id": "a1b2c3d4e5"}

Elasticsearch resource operations

Get Deployment Elasticsearch Resource Info

Retrieves detailed information about the Elasticsearch resource within a deployment.

Parameters:

Name	Type	Required	Description
`deploymentId`	`string`	Yes	Identifier for the deployment.
`refId`	`string`	Yes	User-specified RefId for the resource (or `_main` if there is only one).

Returns: ElasticsearchResourceInfo|error

Sample code:

elasticcloud:ElasticsearchResourceInfo esInfo = check elasticClient->/deployments/["a1b2c3d4e5"]/elasticsearch/["main-elasticsearch"]();

Sample response:

{"ref_id": "main-elasticsearch", "id": "es-abc123", "region": "gcp-asia-south1", "info": {"healthy": true, "status": "started"}}

Reset Elasticsearch user password

Resets the password for the elastic user on the specified Elasticsearch resource.

Parameters:

Name	Type	Required	Description
`deploymentId`	`string`	Yes	Identifier for the deployment.
`refId`	`string`	Yes	User-specified RefId for the Elasticsearch resource.

Returns: ElasticsearchElasticUserPasswordResetResponse|error

Sample code:

elasticcloud:ElasticsearchElasticUserPasswordResetResponse resetResp = check elasticClient->/deployments/["a1b2c3d4e5"]/elasticsearch/["main-elasticsearch"]/_reset\-password.post();

Sample response:

{"username": "elastic", "password": "newGeneratedPassword123"}

Get Elasticsearch keystore

Retrieves the keystore contents for the specified Elasticsearch resource.

Parameters:

Name	Type	Required	Description
`deploymentId`	`string`	Yes	Identifier for the deployment.
`refId`	`string`	Yes	User-specified RefId for the Elasticsearch resource.

Returns: KeystoreContents|error

Sample code:

elasticcloud:KeystoreContents keystore = check elasticClient->/deployments/["a1b2c3d4e5"]/elasticsearch/["main-elasticsearch"]/keystore();

Sample response:

{"secrets": {"s3.client.default.access_key": {"as_file": false}}}

Get remote clusters

Retrieves the remote cluster configuration for cross-cluster search and replication.

Parameters:

Name	Type	Required	Description
`deploymentId`	`string`	Yes	Identifier for the deployment.
`refId`	`string`	Yes	User-specified RefId for the Elasticsearch resource.

Returns: RemoteResources|error

Sample code:

elasticcloud:RemoteResources remoteClusters = check elasticClient->/deployments/["a1b2c3d4e5"]/elasticsearch/["main-elasticsearch"]/remote\-clusters();

Sample response:

{"resources": []}

Extension operations

List Extensions

Retrieves all available extensions.

Returns: Extensions|error

Sample code:

elasticcloud:Extensions extensions = check elasticClient->/deployments/extensions();

Sample response:

{"extensions": [{"id": "ext-001", "name": "custom-analyzer", "extension_type": "bundle", "description": "Custom analysis plugin"}]}

Create an extension

Creates a new extension for use with Elasticsearch deployments.

Parameters:

Name	Type	Required	Description
`payload`	`CreateExtensionRequest`	Yes	The extension creation data including name, type, and version.

Returns: Extension|error

Sample code:

elasticcloud:Extension ext = check elasticClient->/deployments/extensions.post({
    name: "my-plugin",
    extension_type: "bundle",
    version: "8.17.*"
});

Sample response:

{"id": "ext-002", "name": "my-plugin", "extension_type": "bundle"}

Get Extension

Retrieves the details of a specific extension.

Parameters:

Name	Type	Required	Description
`extensionId`	`string`	Yes	Identifier for the extension.

Returns: Extension|error

Sample code:

elasticcloud:Extension ext = check elasticClient->/deployments/extensions/["ext-001"]();

Sample response:

{"id": "ext-001", "name": "custom-analyzer", "extension_type": "bundle", "description": "Custom analysis plugin", "deployments": ["a1b2c3d4e5"]}

Delete Extension

Deletes an extension by its ID.

Parameters:

Name	Type	Required	Description
`extensionId`	`string`	Yes	Identifier for the extension.

Returns: EmptyResponse|error

Sample code:

elasticcloud:EmptyResponse _ = check elasticClient->/deployments/extensions/["ext-001"].delete();

Traffic filter operations

List traffic filter rulesets

Retrieves all traffic filter rulesets.

Parameters:

Name	Type	Required	Description
`queries`	`GetTrafficFilterRulesetsQueries`	No	Query parameters to filter rulesets by region or include associations.

Returns: TrafficFilterRulesets|error

Sample code:

elasticcloud:TrafficFilterRulesets rulesets = check elasticClient->/deployments/traffic\-filter/rulesets();

Sample response:

{"rulesets": [{"id": "tf-001", "name": "office-ip-filter", "type": "ip", "include_by_default": false, "rules": [{"source": "203.0.113.0/24"}]}]}

Create traffic filter ruleset

Creates a new traffic filter ruleset for controlling network access.

Parameters:

Name	Type	Required	Description
`payload`	`TrafficFilterRulesetRequest`	Yes	The ruleset definition including name, type, and rules.

Returns: TrafficFilterRulesetResponse|error

Sample code:

elasticcloud:TrafficFilterRulesetResponse ruleset = check elasticClient->/deployments/traffic\-filter/rulesets.post({
    name: "office-ip-filter",
    'type: "ip",
    include_by_default: false,
    rules: [{source: "203.0.113.0/24"}]
});

Sample response:

{"id": "tf-002"}

Delete traffic filter ruleset

Deletes a traffic filter ruleset by its ID.

Parameters:

Name	Type	Required	Description
`rulesetId`	`string`	Yes	Identifier for the traffic filter ruleset.

Returns: EmptyResponse|error

Sample code:

elasticcloud:EmptyResponse _ = check elasticClient->/deployments/traffic\-filter/rulesets/["tf-001"].delete();

Create traffic filter ruleset association

Associates a traffic filter ruleset with a deployment.

Parameters:

Name	Type	Required	Description
`rulesetId`	`string`	Yes	Identifier for the traffic filter ruleset.
`payload`	`FilterAssociation`	Yes	The association definition including entity type and ID.

Returns: EmptyResponse|error

Sample code:

elasticcloud:EmptyResponse _ = check elasticClient->/deployments/traffic\-filter/rulesets/["tf-001"]/associations.post({
    entity_type: "deployment",
    id: "a1b2c3d4e5"
});

Deployment template & stack version operations

Get deployment templates

Retrieves available deployment templates for creating new deployments.

Parameters:

Name	Type	Required	Description
`queries`	`GetDeploymentTemplatesV2Queries`	No	Query parameters including `region` and `stack_version`.

Returns: DeploymentTemplateInfoV2[]|error

Sample code:

elasticcloud:DeploymentTemplateInfoV2[] templates = check elasticClient->/deployments/templates(queries = {region: "gcp-asia-south1"});

Sample response:

[{"id": "gcp-general-purpose", "name": "General Purpose", "description": "A general purpose deployment template"}]

Get available Elastic Stack versions

Retrieves all available Elastic Stack versions including template version and structure.

Parameters:

Name	Type	Required	Description
`queries`	`GetVersionStacksQueries`	No	Query parameters including `show_deleted` and `show_unusable`.

Returns: StackVersionConfigs|error

Sample code:

elasticcloud:StackVersionConfigs versions = check elasticClient->/stack/versions();

Sample response:

{"stacks": [{"version": "8.17.0", "accessible": true, "min_upgradable_from": "7.17.0"}]}

Organization operations

List organizations

Retrieves all organizations accessible to the authenticated user.

Returns: OrganizationList|error

Sample code:

elasticcloud:OrganizationList orgs = check elasticClient->/organizations();

Sample response:

{"organizations": [{"id": "org-abc123", "name": "My Organization"}]}

Fetch organization information

Retrieves detailed information about a specific organization.

Parameters:

Name	Type	Required	Description
`organizationId`	`string`	Yes	Identifier for the organization.

Returns: Organization|error

Sample code:

elasticcloud:Organization org = check elasticClient->/organizations/["org-abc123"]();

Sample response:

{"id": "org-abc123", "name": "My Organization", "default_disk_usage_alerts_enabled": true}

Update organization

Updates an organization's settings.

Parameters:

Name	Type	Required	Description
`organizationId`	`string`	Yes	Identifier for the organization.
`payload`	`OrganizationRequest`	Yes	The organization update payload.

Returns: Organization|error

Sample code:

elasticcloud:Organization updated = check elasticClient->/organizations/["org-abc123"].put({
    notifications_allowed_email_domains: ["example.com"]
});

Sample response:

{"id": "org-abc123", "name": "My Organization", "notifications_allowed_email_domains": ["example.com"]}

Get organization members

Retrieves all members of an organization.

Parameters:

Name	Type	Required	Description
`organizationId`	`string`	Yes	Identifier for the organization.

Returns: OrganizationMemberships|error

Sample code:

elasticcloud:OrganizationMemberships members = check elasticClient->/organizations/["org-abc123"]/members();

Sample response:

{"members": [{"user_id": "user-001", "email": "[email protected]", "organization_id": "org-abc123"}]}

Create organization invitation

Sends invitations to join an organization.

Parameters:

Name	Type	Required	Description
`organizationId`	`string`	Yes	Identifier for the organization.
`payload`	`OrganizationInvitationRequest`	Yes	The invitation request with email addresses.

Returns: OrganizationInvitations|error

Sample code:

elasticcloud:OrganizationInvitations invitations = check elasticClient->/organizations/["org-abc123"]/invitations.post({
    emails: ["[email protected]"]
});

Sample response:

{"invitations": [{"token": "inv-token-xyz", "email": "[email protected]", "accepted": false}]}

API key operations

Get all API keys

Retrieves the metadata for all API keys belonging to the authenticated user.

Returns: ApiKeysResponse|error

Sample code:

elasticcloud:ApiKeysResponse allKeys = check elasticClient->/users/auth/keys();

Sample response:

{"keys": [{"id": "key-001", "description": "Production key", "creation_date": "2025-01-15T10:30:00Z"}, {"id": "key-002", "description": "Dev key", "creation_date": "2025-02-20T14:00:00Z", "expiration_date": "2025-08-20T14:00:00Z"}]}

Create API key

Creates a new API key. The key value is returned only once in the response.

Parameters:

Name	Type	Required	Description
`payload`	`CreateApiKeyRequest`	Yes	The API key creation request including description and optional expiration.

Returns: ApiKeyResponse|error

Sample code:

elasticcloud:ApiKeyResponse createdKey = check elasticClient->/users/auth/keys.post({
    description: "API key created from Ballerina"
});

Sample response:

{"id": "key-003", "key": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==", "description": "API key created from Ballerina", "creation_date": "2025-03-17T08:00:00Z"}

Get API key

Retrieves the metadata for a specific API key by ID.

Parameters:

Name	Type	Required	Description
`apiKeyId`	`string`	Yes	The API key ID.

Returns: ApiKeyResponse|error

Sample code:

elasticcloud:ApiKeyResponse keyInfo = check elasticClient->/users/auth/keys/["key-001"]();

Sample response:

{"id": "key-001", "description": "Production key", "creation_date": "2025-01-15T10:30:00Z", "user_id": "user-001", "organization_id": "org-abc123"}

Delete API key

Deletes a specific API key by ID.

Parameters:

Name	Type	Required	Description
`apiKeyId`	`string`	Yes	The API key ID.

Returns: EmptyResponse|error

Sample code:

elasticcloud:EmptyResponse _ = check elasticClient->/users/auth/keys/["key-003"].delete();

Delete API keys

Deletes multiple API keys at once.

Parameters:

Name	Type	Required	Description
`payload`	`DeleteApiKeysRequest`	Yes	The list of API key IDs to delete.

Returns: EmptyResponse|error

Sample code:

elasticcloud:EmptyResponse _ = check elasticClient->/users/auth/keys.delete({
    keys: ["key-002", "key-003"]
});

User role assignment operations

Add Role Assignments

Adds role assignments to a user.

Parameters:

Name	Type	Required	Description
`userId`	`string`	Yes	Identifier for the user.
`payload`	`RoleAssignments`	Yes	The role assignments to add.

Returns: EmptyResponse|error

Sample code:

elasticcloud:EmptyResponse _ = check elasticClient->/users/["user-001"]/role_assignments.post({
    organization: [{organization_id: "org-abc123", role_id: "organization-admin"}]
});

Remove Role Assignments

Removes role assignments from a user.

Parameters:

Name	Type	Required	Description
`userId`	`string`	Yes	Identifier for the user.
`payload`	`RoleAssignments`	Yes	The role assignments to remove.

Returns: EmptyResponse|error

Sample code:

elasticcloud:EmptyResponse _ = check elasticClient->/users/["user-001"]/role_assignments.delete({
    organization: [{organization_id: "org-abc123", role_id: "organization-admin"}]
});

Trust & security operations

Get trusted environments

Retrieves the trusted environment settings for the organization.

Returns: ElasticsearchClusterTrustSettings|error

Sample code:

elasticcloud:ElasticsearchClusterTrustSettings trustSettings = check elasticClient->/trusted\-environments();

Sample response:

{"accounts": [], "external": []}

Get deployment certificate authority

Retrieves the certificate authority for a deployment.

Parameters:

Name	Type	Required	Description
`deploymentId`	`string`	Yes	Identifier for the deployment.

Returns: CertificateAuthority|error

Sample code:

elasticcloud:CertificateAuthority ca = check elasticClient->/deployments/["a1b2c3d4e5"]/certificate\-authority();

Sample response:

{"pem": "-----BEGIN CERTIFICATE-----\nMIIDQTCCAimgAw...\n-----END CERTIFICATE-----\n"}

Client​

Configuration​

Initializing the client​

Operations​

Account operations​

Deployment operations​

Elasticsearch resource operations​

Extension operations​

Traffic filter operations​

Deployment template & stack version operations​

Organization operations​

API key operations​

User role assignment operations​

Trust & security operations​

Client

Configuration

Initializing the client

Operations

Account operations

Deployment operations

Elasticsearch resource operations

Extension operations

Traffic filter operations

Deployment template & stack version operations

Organization operations

API key operations

User role assignment operations

Trust & security operations