API Reference

Manage PostgreSQL databases, branches, computes, and more via REST. Base URL: https://api-test.lampion.cloud/v1/

Every request requires:

Authorization: Bearer lmp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create a key in Settings > API Keys.

Authentication

All API requests require a Bearer token. Create an API key from Settings > API Keys in the console. Keys are scoped to your organization with developer permissions.

Projects

A project is a PostgreSQL database with branching, monitoring, and auto-suspend. Creating a project provisions a compute and returns a ready-to-use connection string.

GET /v1/projects

List all projects.

Request

curl -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects

Response

[{"id":"abc123","name":"my-app","region":"fr-par-1"}]
POST /v1/projects

Create a project. Returns connection string, endpoint, password.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"my-app","region":"fr-par-1"}' https://api-test.lampion.cloud/v1/projects

Response

{"id":"abc123","name":"my-app","endpoint_id":"ep-abc",
 "connection_string":"postgresql://cloud_admin:xxx@db-test.lampion.cloud:5432/ep-abc.postgres?sslmode=require",
 "pg_password":"YaQYfbg...","host":"db-test.lampion.cloud","port":5432}
GET /v1/projects/{project_id}

Get a project by ID.

Request

curl -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}

Response

{"id":"abc123","name":"my-app","region":"fr-par-1"}
DELETE /v1/projects/{project_id}

Delete a project and all data. Irreversible.

Request

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}

Response

204 No Content

Branches

Copy-on-write forks. Create in under a second for testing, staging, or CI.

GET /v1/projects/{id}/branches

List all branches.

Request

curl -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}/branches

Response

[{"id":"tid","name":"main","is_primary":true},{"id":"feat","name":"staging"}]
POST /v1/projects/{id}/branches

Create a branch (fork). Provisions a new compute.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"staging","parent_id":"main-tid"}' https://api-test.lampion.cloud/v1/projects/{id}/branches

Response

{"id":"new-tid","name":"staging","compute_id":"ep-new","pg_port":55436}
DELETE /v1/projects/{id}/branches/{bid}

Delete a branch and its compute.

Request

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}/branches/{bid}

Response

204 No Content

Endpoints (Computes)

PostgreSQL compute instances. Suspend/resume, configure auto-suspend, manage IP allowlists.

GET /v1/projects/{id}/endpoints

List endpoints with connection strings and passwords.

Request

curl -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}/endpoints

Response

[{"id":"ep-abc","status":"running","connection_string":"postgresql://...","pg_password":"xxx"}]
POST .../{eid}/suspend

Suspend (scale to zero).

Request

curl -X POST -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}/suspend

Response

{"id":"ep-abc","status":"suspended"}
POST .../{eid}/resume

Resume a suspended compute.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}/resume

Response

{"id":"ep-abc","status":"running"}
PATCH .../{eid}

Update settings (auto_suspend_seconds).

Request

curl -X PATCH -H "Authorization: Bearer $TOKEN" -d '{"auto_suspend_seconds":600}' https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}

Response

{"id":"ep-abc","auto_suspend_seconds":600}
GET .../{eid}/allowlist

Get IP allowlist.

Request

curl -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}/allowlist

Response

["10.0.0.0/8"]
PUT .../{eid}/allowlist

Replace IP allowlist.

Request

curl -X PUT -H "Authorization: Bearer $TOKEN" -d '{"allowlist":["10.0.0.0/8"]}' https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}/allowlist

Response

["10.0.0.0/8"]
GET /v1/projects/{id}/endpoints/compute-sizes

List available compute sizes (CU tiers).

Request

curl -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}/endpoints/compute-sizes

Response

[{"cu":0.25,"label":"0.25 CU","vcpu":0.25,"memory_gb":0.5},{"cu":1,"label":"1 CU","vcpu":1,"memory_gb":2},{"cu":4,"label":"4 CU","vcpu":4,"memory_gb":8}]
PATCH .../{eid}

Resize compute. Set compute_cu, or enable autoscaling with min_cu/max_cu.

Request

curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -d '{"compute_cu":2,"min_cu":0.5,"max_cu":4}' https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}

Response

{"id":"ep-abc","compute_cu":2,"min_cu":0.5,"max_cu":4}

SQL Execution

Execute queries via the API. Supports multi-statement scripts and psql meta-commands.

POST .../{eid}/sql

Execute SQL. Returns columns, rows, duration.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{"query":"SELECT * FROM users LIMIT 5"}' https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}/sql

Response

{"columns":["id","name"],"rows":[{"id":1,"name":"Alice"}],"duration":12}

Schema Introspection

Browse databases, schemas, tables, and columns.

GET /v1/projects/{id}/schema

No params = databases. ?database=X = schemas. ?database=X&schema=Y = tables + columns.

Request

curl -H "Authorization: Bearer $TOKEN" "https://api-test.lampion.cloud/v1/projects/{id}/schema?database=postgres&schema=public"

Response

{"type":"tables","items":[{"name":"users","columns":[{"name":"id","type":"integer"},{"name":"email","type":"text"}]}]}

Databases

CRUD PostgreSQL databases within an endpoint.

GET .../{eid}/databases

List databases.

Request

curl -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}/databases

Response

[{"name":"postgres","encoding":"UTF8","size_bytes":8945664}]
POST .../{eid}/databases

Create a database.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" -d '{"name":"myapp"}' https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}/databases

Response

{"name":"myapp"}
DELETE .../{eid}/databases/{name}

Drop a database.

Request

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}/databases/myapp

Response

204 No Content

Roles

Manage PostgreSQL roles.

GET .../{eid}/roles

List roles.

Request

curl -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}/roles

Response

[{"name":"cloud_admin","is_superuser":true,"can_login":true}]
POST .../{eid}/roles

Create a role.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" -d '{"name":"appuser","password":"secret","can_login":true}' https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}/roles

Response

{"name":"appuser","can_login":true}
DELETE .../{eid}/roles/{name}

Drop a role.

Request

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}/roles/appuser

Response

204 No Content

Extensions

Install and manage PostgreSQL extensions.

GET .../{eid}/extensions

List extensions.

Request

curl -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}/extensions

Response

[{"name":"plpgsql","installed":true},{"name":"pgvector","installed":false}]
POST .../{eid}/extensions

Install an extension.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" -d '{"name":"pgvector"}' https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}/extensions

Response

{"name":"pgvector","installed":true}
DELETE .../{eid}/extensions/{name}

Uninstall an extension.

Request

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}/extensions/pgvector

Response

204 No Content

Metrics & Usage

Real-time metrics and monthly usage for billing.

GET /v1/projects/{id}/metrics

Live: connections, cache ratio, storage, CPU, memory.

Request

curl -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}/metrics

Response

{"connections_total":5,"cache_hit_ratio":98.5,"storage_logical_mb":42.3,"compute_cpu_seconds":123.4}
GET /v1/projects/{id}/metrics/history

Historical metrics (24h max, every 30s).

Request

curl -H "Authorization: Bearer $TOKEN" "https://api-test.lampion.cloud/v1/projects/{id}/metrics/history?hours=6"

Response

[{"snapshot_at":"...","connections_total":3,"storage_logical_mb":42.1}]
GET /v1/projects/{id}/usage

Monthly: compute hours, storage GB, transfer GB.

Request

curl -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/projects/{id}/usage

Response

{"compute_hours":12.5,"storage_gb":0.042,"transfer_total_gb":0.001,"period":"2026-03"}
GET /v1/usage

Org-wide usage with plan info and cost estimation.

Request

curl -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/usage

Response

{"plan":{"name":"dev"},"total":{"compute_hours":25},"estimated_cost":{"total_usd":2.65}}

Logs

PostgreSQL server logs.

GET .../{eid}/logs

Tail PG logs. ?lines=N (default 200, max 5000).

Request

curl -H "Authorization: Bearer $TOKEN" "https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}/logs?lines=50"

Response

{"lines":["2026-03-30 LOG: connection authorized"],"count":50}

Backup & Dump

pg_dump via the API.

GET .../{eid}/dump

Download pg_dump SQL. ?database=X&table=Y for single table.

Request

curl -H "Authorization: Bearer $TOKEN" "https://api-test.lampion.cloud/v1/projects/{id}/endpoints/{eid}/dump" -o dump.sql

Response

-- SQL dump saved to dump.sql

Webhooks

HTTP notifications on events. Payloads signed HMAC-SHA256.

GET /v1/orgs/webhooks

List webhooks.

Request

curl -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/orgs/webhooks

Response

[{"id":"wh-abc","url":"https://...","events":["*"],"enabled":true}]
POST /v1/orgs/webhooks

Create webhook. Returns signing secret.

Request

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -d '{"url":"https://hook.example.com","events":["project.created"]}' https://api-test.lampion.cloud/v1/orgs/webhooks

Response

{"id":"wh-abc","secret":"a1b2c3...","events":["project.created"]}
PATCH /v1/orgs/webhooks/{id}

Update webhook.

Request

curl -X PATCH -H "Authorization: Bearer $TOKEN" -d '{"enabled":false}' https://api-test.lampion.cloud/v1/orgs/webhooks/{id}

Response

{"id":"wh-abc","enabled":false}
DELETE /v1/orgs/webhooks/{id}

Delete webhook.

Request

curl -X DELETE -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/orgs/webhooks/{id}

Response

204 No Content

Plans

Pricing plans.

GET /v1/plans

List plans with limits and pricing.

Request

curl -H "Authorization: Bearer $TOKEN" https://api-test.lampion.cloud/v1/plans

Response

[{"name":"free","max_projects":3,"cu_hour_usd":0},{"name":"dev","cu_hour_usd":0.106},{"name":"pro","cu_hour_usd":0.106}]