API reference

The API is a JSON-over-HTTPS interface at https://api.cloisterlabs.com/v1. Everything the console and CLI do goes through it.

Authentication

Send a project token as a bearer token:

GET /v1/nodes
Authorization: Bearer clt_live_…

Tokens are scoped to one project. Create read-only tokens for monitoring and keep write tokens out of CI logs.

Resources

Resource	Endpoints
Plans	GET /v1/plans
Nodes	GET /v1/nodes · POST /v1/nodes · GET /v1/nodes/{id} · DELETE /v1/nodes/{id}
Attestation	GET /v1/nodes/{id}/attestation?nonce=
Clusters	GET /v1/clusters · POST /v1/clusters · GET /v1/clusters/{id}
Volumes	GET /v1/volumes · POST /v1/volumes · POST /v1/volumes/{id}/attach
Access requests	GET /v1/access-requests · POST /v1/access-requests/{id}/approve
Audit log	GET /v1/audit

Creating a node

POST /v1/nodes
Content-Type: application/json

{
  "plan": "cl.h200.x8",
  "region": "eu-n",
  "confidential": true,
  "ssh_keys": ["ssh-ed25519 AAAA…"]
}

{
  "id": "node_7Hq2",
  "plan": "cl.h200.x8",
  "region": "eu-n",
  "state": "provisioning",
  "confidential": true,
  "created_at": "2026-10-15T09:12:44Z"
}

Errors

Errors use standard HTTP status codes and a consistent body:

{
  "error": {
    "code": "capacity_unavailable",
    "message": "No cl.b200.x8 nodes are available in eu-n.",
    "retryable": true
  }
}

Status	Code	Meaning
400	invalid_request	A field is missing or malformed
401	unauthenticated	Token missing, expired or revoked
403	forbidden	Token lacks the required scope
409	conflict	The resource is in a state that does not allow this action
422	capacity_unavailable	No capacity for this plan and region right now
429	rate_limited	Too many requests; see Limits

Pagination

List endpoints return up to 100 items and a next cursor. Pass it back as ?cursor= until it is null.

Idempotency

Send an Idempotency-Key header on POST requests. Retrying with the same key within 24 hours returns the original result instead of creating a second resource.