Deployments

Discover capacity, preview costs, and manage deployment creation, upgrades, and deletion

API Variables

ld-api-key

{tenant_id}

Set variables to auto-fill all examples and run requests in-browser.

Use api.laserdata.cloud for deployment creation, upgrades, and deletion. Use {supervisor_url} for runtime status, nodes, and credentials. See API Architecture.

Reading requires deployment:read. Creation, changes, and deletion require deployment:manage.

Discovery

Before creating a deployment, retrieve the configurations available to your plan and region.

List Available Clouds

GET

/tenants/{tenant_id}/clouds

List cloud providers available to the tenant.

bash

curl https://api.laserdata.cloud/tenants/{tenant_id}/clouds \
-H "ld-api-key: YOUR_API_KEY"

List Regions

GET

/tenants/{tenant_id}/clouds/{cloud}/regions

List regions available for a given cloud provider.

bash

curl https://api.laserdata.cloud/tenants/{tenant_id}/clouds/aws/regions \
-H "ld-api-key: YOUR_API_KEY"

List Available Tiers

GET

/tenants/{tenant_id}/clouds/{cloud}/regions/{region}/tiers

List the Compute sizes available in a region for the tenant, with resources, supported storage, and remaining counts.

bash

curl https://api.laserdata.cloud/tenants/{tenant_id}/clouds/aws/regions/us-west-1/tiers \
-H "ld-api-key: YOUR_API_KEY"

[
  {
    "key": "free",
    "name": "Free",
    "description": "Perfect for getting started.",
    "available": true,
    "limit": 1,
    "clusters": ["standalone"],
    "storages": ["network_balanced"],
    "rate_limit": "100 KB/s"
  },
  {
    "key": "large",
    "name": "Large",
    "available": true,
    "limit": 2,
    "clusters": ["cluster"],
    "storages": ["local_ssd", "network_balanced"],
    "rate_limit": null
  }
]

List Available Storage Types

GET

/tenants/{tenant_id}/clouds/{cloud}/regions/{region}/storages

List the storage types available to the tenant in a region.

bash

curl https://api.laserdata.cloud/tenants/{tenant_id}/clouds/aws/regions/us-west-1/storages \
-H "ld-api-key: YOUR_API_KEY"

Create Deployments

Preview Deployment Cost

POST

/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/preview

Validate a deployment shape and return its monthly configuration price, estimated total, and technical sizing metadata without provisioning it.

curl -X POST https://api.laserdata.cloud/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/preview \
  -H "ld-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cloud": "aws",
    "region": "us-east-1",
    "managed_tier": "standard",
    "tier": "small",
    "storage": { "type": "network_balanced", "size": 100 },
    "target_network_tput": 100,
    "network_scope": "same_region",
    "availability_mode": "single_az"
  }'

A paid preview requires managed_tier, cloud, region, and tier. A Free preview omits managed_tier and returns zero cost. Preview accepts storage, throughput, network scope, and availability without creating resources. The product determines node count, so the request has no node-count field.

The response reports cloud, region, tier, nodes, compute_profile_id, included_telemetry_days, pricing_version, monthly_base_usd, and monthly_total_usd. breakdown contains compute_usd, storage_usd, and network_usd. capacity reports shards_per_node, default_segment_bytes, min_segment_bytes, partitions_per_node_at_default_segment, and partitions_per_node_at_min_segment.

target_network_tput uses KB/s. 100 means 0.1 MB/s, and 1000 means 1 MB/s. Omit it to use the tier's default throughput estimate. If storage is omitted, preview uses 100 GB of Network Drive per node. If availability is omitted, preview uses Single AZ. Preview requires deployment:read. monthly_base_usd excludes transfer. monthly_total_usd includes estimated transfer, which is billed for actual usage. Segment-based capacity fields are diagnostic values, not guaranteed partition limits.

Create a Managed Deployment

POST

/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/managed

Provision a fully managed deployment on LaserData infrastructure.

bash

curl -X POST https://api.laserdata.cloud/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/managed \
-H "ld-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "name": "prod-cluster",
  "cloud": "aws",
  "region": "us-west-1",
  "managed_tier": "standard",
  "tier": "small",
  "cluster": "cluster",
  "storage": {
    "type": "network_balanced",
    "size": 250
  },
  "target_network_tput": 1000,
  "network_scope": "same_region",
  "availability_mode": "single_az",
  "protected": true,
  "encrypted": true,
  "public_ip_enabled": true,
  "subdomain_enabled": true,
  "retention": {
    "telemetry_days": 14
  },
  "spend_limit": 500.00
}'

Field	Required	Values / Description
`name`	Yes	Deployment name
`cloud`	Yes	`aws` or `gcp`
`region`	Yes	Cloud region, for example `us-west-1` or `europe-west1`
`managed_tier`	Paid	`standard`, `performance`, or `enterprise`. Required for every paid deployment and omitted for Free
`tier`	Yes	Compute size: `free`, `small`, `medium`, `large`, `xlarge`, `2xlarge`, `4xlarge`, `8xlarge`, or `16xlarge`
`cluster`	Yes	`cluster` for paid deployments. Free uses `standalone`
`storage.type`	No	`network_balanced` for Network Drive or `local_ssd` for Local NVMe. Defaults to 100 GB of Network Drive per node
`storage.size`	No	Network Drive size in GB per node, from 100 to 30,000. Local NVMe size follows the Compute size
`target_network_tput`	No	Throughput estimate in KB/s. Defaults to the tier's default throughput estimate. Used for compute sizing and estimating transfer, never a transfer commitment or paid broker rate limit
`network_scope`	No	`same_region` (default), `cross_region_same_cloud`, or `cross_cloud`
`availability_mode`	No	`single_az` (default) or `multi_az`. Multi AZ requires Enterprise
`protected`	No	Enable resource protection. Default `false`
`encrypted`	No	Enable custom key encryption of message data. Default `false`
`public_ip_enabled`	No	Assign a static public IP. Default `true`
`subdomain_enabled`	No	Assign a custom subdomain. Requires a public IP. Default `true`
`dedicated`	No	Dedicated infrastructure isolation. Requires the Enterprise plan entitlement. Default `false`
`retention.telemetry_days`	No	Telemetry retention in days. Defaults to 14 days for Standard, 30 for Performance, or 90 for Enterprise. Free uses 7 days. Higher values are rejected
`spend_limit`	No	Monthly spend monitoring threshold in USD

Catalog presets do not override omitted creation fields. To create an Enterprise preset with Local NVMe and Multi AZ, send its storage and availability explicitly.

The endpoint returns 202 Accepted with resource IDs in ld-environment and ld-deployment. Valid payment information is required. Local NVMe requires Performance or Enterprise. Multi AZ requires Enterprise. Unsupported tier features return 400 with field_issues.

Generate BYOC Setup

POST

/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/byoc/setup

Generate the trust policy and permissions policy needed to create a BYOC deployment. Returns cloud-specific setup instructions.

bash

curl -X POST https://api.laserdata.cloud/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/byoc/setup \
-H "ld-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "cloud": "aws",
  "region": "us-west-1"
}'

AWS setup returns laserdata_org_id, external_id, trust_policy, and permissions_policy. GCP setup returns service-account instructions.

Validate BYOC Credentials

POST

{supervisor_url}/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/byoc/validate

Validate that the provided credentials are correctly configured before creating the deployment.

bash

curl -X POST {supervisor_url}/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/byoc/validate \
-H "ld-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "cloud": "aws",
  "region": "us-west-1",
  "account_id": "123456789012",
  "identity_arn": "arn:aws:iam::123456789012:role/LaserDataByocRole",
  "external_id": "unique-external-id-123",
  "vpc_id": "vpc-12345678"
}'

Create a BYOC Deployment (AWS)

POST

/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/byoc

Deploy to your own AWS account. Use the cloud deployment fields and an aws object with IAM role details. Managed commercial fields do not apply.

bash

curl -X POST https://api.laserdata.cloud/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/byoc \
-H "ld-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "name": "prod-byoc",
  "cloud": "aws",
  "tier": "large",
  "cluster": "cluster",
  "region": "us-east-1",
  "storage": {
    "type": "network_balanced",
    "size": 500
  },
  "aws": {
    "account_id": "123456789012",
    "identity_arn": "arn:aws:iam::123456789012:role/LaserDataByocRole",
    "external_id": "your-external-id",
    "vpc_id": "vpc-0abc123def456",
    "vpc_cidr": "10.0.0.0/16"
  }
}'

A successful request returns 202 Accepted with ld-environment and ld-deployment. See BYOC Setup for IAM configuration.

Create a BYOC Deployment (GCP)

POST

/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/byoc

Deploy to your own GCP project using a service account. Pass a gcp object instead of aws.

bash

curl -X POST https://api.laserdata.cloud/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/byoc \
-H "ld-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "name": "byoc-gcp-prod",
  "cloud": "gcp",
  "tier": "large",
  "cluster": "cluster",
  "region": "europe-west1",
  "storage": {
    "type": "network_balanced",
    "size": 100
  },
  "gcp": {
    "project_id": "my-gcp-project-123",
    "service_account_email": "laserdata-byoc@my-gcp-project-123.iam.gserviceaccount.com",
    "vpc_name": "default"
  }
}'

A successful request returns 202 Accepted with ld-environment and ld-deployment.

Create a Starter Deployment

POST

/tenants/{tenant_id}/divisions/{division_id}/deployments/starter

Create a Free single-node deployment on shared infrastructure for development or testing.

bash

curl -X POST https://api.laserdata.cloud/tenants/{tenant_id}/divisions/{division_id}/deployments/starter \
-H "ld-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "cloud": "aws",
  "region": "us-west-1"
}'

Field	Required	Description
`cloud`	Yes	`aws`, `gcp`
`region`	Yes	Cloud region
`environment_id`	No	Existing environment ID to deploy into
`environment_name`	No	Name for a new environment (defaults to `sandbox`)
`deployment_name`	No	Deployment name (auto-generated if omitted)

Read Deployments

List Deployments

GET

/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments

List all deployments in an environment.

bash

curl https://api.laserdata.cloud/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments \
-H "ld-api-key: YOUR_API_KEY"

{
  "items": [
    {
      "id": 1,
      "name": "prod-cluster",
      "code": "abc123",
      "variant": "managed",
      "domain": "prod-cluster-abc123.laserdata.cloud",
      "cloud": "aws",
      "region": "us-west-1",
      "tier": "large",
      "cluster": "cluster",
      "supervisor_url": "https://supervisor-aws-us.laserdata.cloud",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "page": 1,
  "total_results": 1,
  "total_pages": 1
}

Get Deployment (Main API)

GET

/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/{deployment_id}

Retrieve business metadata: protection, description, and upgrade history.

bash

curl https://api.laserdata.cloud/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/{deployment_id} \
-H "ld-api-key: YOUR_API_KEY"

The Main API adds code, protected, description, and upgrades. Managed deployments with pricing terms include managed_tier and monthly_base. These describe their active terms and can change after an upgrade or an agreed terms update. target_network_tput reports the throughput estimate. can_upgrade reports whether the cooldown permits a change.

Get Deployment (Supervisor API)

GET

{supervisor_url}/deployments/{deployment_id}

Retrieve live runtime status, node IPs, active configs, and cloud networking info.

bash

curl {supervisor_url}/deployments/{deployment_id} \
-H "ld-api-key: YOUR_API_KEY"

The Supervisor adds status, network_mode, cidr, configs, nodes, and aws or gcp network details.

Request both responses in parallel for the full deployment details.

Get Deployment Credentials

GET

{supervisor_url}/deployments/{deployment_id}/credentials

Retrieve the Iggy username and password for client connections.

bash

curl {supervisor_url}/deployments/{deployment_id}/credentials \
-H "ld-api-key: YOUR_API_KEY"

{
  "username": "iggy",
  "password": "your-deployment-password"
}

Modify Deployments

Upgrade a Deployment

POST

/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/{deployment_id}/upgrade

Move to a larger Compute size, grow Network Drive storage, or move to a higher tier. At least one of tier, storage, or managed_tier is required.

bash

curl -X POST https://api.laserdata.cloud/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/{deployment_id}/upgrade \
-H "ld-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "tier": "xlarge",
  "storage": {
    "type": "network_balanced",
    "size": 500
  }
}'

The endpoint returns 202 Accepted. Warden applies hardware changes asynchronously. Storage cannot shrink. This endpoint cannot change Compute or Storage on Local NVMe deployments.

A tier-only upgrade sends {"managed_tier":"performance"}. It changes commercial terms and telemetry retention without changing hardware. Monthly pricing changes from the effective time, with charges calculated for each active period. This endpoint rejects downgrades, which require agreed terms. Enterprise requires approved account features. Every upgrade requires valid payment information.

Extend a Deployment

POST

/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/{deployment_id}/extend

Reserved endpoint. Adding nodes is not currently supported.

The request has a nodes array, such as [{"count": 2}], but an authorized call for an existing deployment returns cluster_extension_not_allowed. Use supported Compute or Storage upgrades instead.

Update Spend Limit

PUT

/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/{deployment_id}/spend_limit

Set or update the monthly spend monitoring threshold in USD.

bash

curl -X PUT https://api.laserdata.cloud/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/{deployment_id}/spend_limit \
-H "ld-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "spend_limit": 1000.00
}'

A successful request returns 200 OK. It requires environment-level deployment:manage.

Update Retention

PUT

/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/{deployment_id}/retention

Update telemetry retention period for metrics, logs, and heartbeats.

bash

curl -X PUT https://api.laserdata.cloud/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/{deployment_id}/retention \
-H "ld-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "retention": {
    "telemetry_days": 14
  }
}'

A successful request returns 200 OK.

Update Deployment

PUT

/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/{deployment_id}

Update protection status or description.

bash

curl -X PUT https://api.laserdata.cloud/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/{deployment_id} \
-H "ld-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "protected": true,
  "description": "Production streaming cluster for analytics pipeline"
}'

Delete a Deployment

DELETE

/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/{deployment_id}

Permanently delete a deployment. Protected deployments require a resource code. This action is irreversible.

bash

curl -X DELETE "https://api.laserdata.cloud/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/{deployment_id}?code={protection_code}" \
-H "ld-api-key: YOUR_API_KEY"

The endpoint returns 202 Accepted. Deletion permanently destroys all nodes, data, configuration, backups, and telemetry.

Deployments

Discovery

List Available Clouds

List Regions

List Available Tiers

List Available Storage Types

Create Deployments

Preview Deployment Cost

Create a Managed Deployment

Generate BYOC Setup

Validate BYOC Credentials

Create a BYOC Deployment (AWS)

Create a BYOC Deployment (GCP)

Create a Starter Deployment

Read Deployments

List Deployments

Get Deployment (Main API)

Get Deployment (Supervisor API)

Get Deployment Credentials

Modify Deployments

Upgrade a Deployment

Extend a Deployment

Update Spend Limit

Update Retention

Update Deployment

Delete a Deployment

Deployment Guide

BYOC Setup

Configuration

Networking

On this page