API Reference

LaserData Cloud exposes three REST API layers. All share the same authentication model: an ld-api-key header bearing an API key scoped to a role with the required permissions.

Base URLs

The supervisor_url for each deployment is returned in the List Deployments and Get Deployment responses, for example https://supervisor-aws-us.laserdata.cloud.

OpenAPI Schema

Every public service publishes an OpenAPI 3.1 spec with a built-in browser. Specs include real request and response examples.

Main, Audit, Notifier

Browse all three at api.laserdata.cloud/docs - a single page with a dropdown that switches between the Core, Audit, and Notifier specs.

Supervisor (per region)

Each supervisor exposes its own spec at /docs. One UI per cloud + area pair:

Every spec declares both ld_api_key and session_cookie security schemes. Endpoints reachable only from a Console session (user-scope paths like account read or invitation accept) declare the cookie scheme explicitly and reject API keys at runtime - see Authentication.

Authentication

Every request must include the ld-api-key header:

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

See Authentication for the full security model, scopes, and error reference.

Pagination

List endpoints support page-based pagination via query parameters:

Paginated responses always include page, total_results, and total_pages fields alongside items. They also carry an RFC 8288 Link response header with rel="first", prev, next, and last URIs so clients can walk pages without parsing the body.

Request and Response Headers

Idempotency

Mutating endpoints (POST, PUT, PATCH) accept an optional idempotency-key header. The platform caches the first response per (api_key, idempotency-key) pair for 10 minutes. Retrying with the same key and the same request body returns the original response with idempotent-replayed: true - the handler is not run a second time.

• Idempotency is keyed per API key, so the feature is only active when authenticated with an API key (Console session traffic does not opt in).
• Replaying with the same key but a different body returns 409 Conflict (code: idempotency_error).
• Replaying while the original request is still in flight returns 409 Conflict (code: idempotent_request_in_progress). Retry shortly.
• DELETE is excluded because the server treats it as natively idempotent.
• The Audit API has no mutating endpoints, so it does not advertise idempotency support.

This lets retry-on-failure logic on network blips, CI re-runs, and queue redelivery stay safe even on side-effecting endpoints like create-deployment.

Quick Start

Spin up a Free-tier deployment in seconds:

# 1. Create a starter deployment (Free tier, standalone)
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"
}'

# Response headers contain the created resource IDs:
# ld-environment: <environment_id>
# ld-deployment: <deployment_id>

# 2. Get the deployment (once provisioned)
curl https://api.laserdata.cloud/tenants/{tenant_id}/divisions/{division_id}/environments/{environment_id}/deployments/{deployment_id} \
-H "ld-api-key: YOUR_API_KEY"

# 3. Get connection credentials
curl {supervisor_url}/deployments/{deployment_id}/credentials \
-H "ld-api-key: YOUR_API_KEY"

HTTP Status Codes

API Sections