platform>docssolutionspricingcontact

Clusters, Nodes & Databases

Clusters, nodes, managed databases, and templates.

Clusters

A cluster is the node group where tasks run.

Cluster types: managed | self_managed | local

GET /api/v1/clusters

List all clusters.

curl http://localhost:47080/api/v1/clusters
[
  {
    "id": "uuid", "name": "main", "type": "local", "description": null,
    "config": {}, "node_count": 2, "running_tasks": 5,
    "created_at": "...", "updated_at": "..."
  }
]

GET /api/v1/clusters/

Fetch a single cluster including node_count and running_tasks.

Nodes

Node status: ready | not_ready | draining | down

GET /api/v1/nodes

List all nodes.

curl http://localhost:47080/api/v1/nodes

GET /api/v1/nodes/

Fetch a single node.

POST /api/v1/nodes//drain

Mark a node as draining — the scheduler stops placing new tasks on it. Existing tasks continue until they stop naturally.

curl -X POST http://localhost:47080/api/v1/nodes/$NODE_ID/drain

Managed databases

Managed databases are provisioned on a cluster and can be bound to an app (which injects DATABASE_URL and related connection vars into the app's env).

POST /api/v1/managed-databases — Create

Body

  • cluster_id (UUID): The cluster to provision on
  • name (string): Human-readable name
  • engine (string, optional): e.g. "postgres"
  • version (string, optional): e.g. "16"
curl -X POST http://localhost:47080/api/v1/managed-databases \
  -H 'Content-Type: application/json' \
  -d '{"cluster_id":"uuid","name":"my-postgres","engine":"postgres","version":"16"}'

GET /api/v1/managed-databases/

{
  "id": "uuid", "cluster_id": "uuid", "name": "my-postgres",
  "engine": "postgres", "version": "16", "status": "ready",
  "connection_host": "localhost", "connection_port": 5432,
  "connection_user": "app", "connection_database": "app",
  "app_id": null, "created_at": "...", "updated_at": "..."
}

Status values: creating, ready, error, deleting

GET /api/v1/managed-databases

List all managed databases.

DELETE /api/v1/managed-databases/

204 No Content.

POST /api/v1/managed-databases//bind — Bind to app

Binds the database to an app, injecting connection env vars into the app.

Body — app_id (UUID)

curl -X POST http://localhost:47080/api/v1/managed-databases/$DB_ID/bind \
  -H 'Content-Type: application/json' \
  -d '{"app_id":"uuid"}'

Templates (one-click installs)

Templates are pre-packaged app definitions — the "one-click install" entries in the dashboard.

GET /api/v1/templates

List available templates.

GET /api/v1/templates/

Fetch a single template.

POST /api/v1/templates//instantiate

Create an app (and optionally a deployment) from a template. The request body shape depends on the template's defined parameters.

Stats & platform config

GET /health

curl http://localhost:47080/health
# {"status":"healthy","version":"0.1.0"}

GET /api/v1/stats

Platform-wide summary: total apps, deployments, tasks, nodes.

GET /api/v1/platform/config

Public platform configuration returned to the dashboard (domains, feature flags, etc.).

See also