REST API Reference

Base URL: http://your-server:8000

All endpoints that modify state require an X-API-Key header (unless HMDB_AUTH_DISABLED=1).

Authentication

X-API-Key: hmdb_yoursecretkey

Roles:

Role	Description
readonly	Read-only queries, health checks, metrics
readwrite	All reads + insert, delete, compact, batch
admin	All of the above + key management, backup, DDL

Health

GET /health/live

Kubernetes liveness probe. No authentication required.

Response 200:

{ "status": "live" }

---

GET /health/ready

Kubernetes readiness probe. No authentication required.

Response 200:

{ "status": "ready" }

---

GET /health

Full database statistics. Requires readonly.

Response 200:

{
  "status": "ok",
  "version": "1.0.0",
  "db_dir": "/data",
  "total_records": 1000000,
  "bucket_count": 100,
  "bucket_seconds": 10,
  "node_count": 5000,
  "wal_pending": 0,
  "uptime_seconds": 3600.5
}

---

GET /metrics

Prometheus text format. Requires readonly.

# HELP hypermeshdb_records_total Total records in TPI index
# TYPE hypermeshdb_records_total gauge
hypermeshdb_records_total 1000000
...

Query

POST /v1/query

Execute any Cypher statement. Requires readwrite for writes, readonly for reads.

Request:

{
  "query": "MATCH HYPEREDGE (he:CoProximity) WHERE he.event_ts >= 1000 RETURN *",
  "parameters": { "start": 1000 }
}

Response 200:

{
  "columns": ["event_ts", "members", "weight"],
  "rows": [{ "event_ts": 1000, "members": [1, 2, 3], "weight": 0.95 }
  ],
  "num_tuples": 1,
  "query_plan": {
    "strategy":        "TPI_BUCKET_PUSHDOWN",
    "buckets_scanned": 3,
    "total_buckets":   100,
    "speedup_factor":  33.3,
    "elapsed_us":      42
  }
}

Hyperedges

GET /v1/hyperedges

Temporal range query (TPI pushdown). Requires readonly.

Query param	Type	Required	Description
start_ts	int	yes	Inclusive start timestamp
end_ts	int	yes	Inclusive end timestamp
table	string	no	Table name (default: primary table)

---

POST /v1/hyperedges

Insert a single hyperedge. Requires readwrite.

Request:

{
  "event_ts":    1000,
  "members":     [1, 2, 3],
  "weight":      0.95,
  "mean_dist_m": 5.2,
  "formation":   "delta",
  "table":       "CoProximity"
}

---

DELETE /v1/hyperedges

Write a tombstone (soft delete). Requires readwrite.

{ "event_ts": 1000, "members": [1, 2, 3] }

---

GET /v1/hyperedges/node/{node_id}

FMI membership lookup. Requires readonly.

Query param	Type	Description
table	string	Table name (default: primary)

---

POST /v1/hyperedges/compact

Compact WAL. Requires readwrite.

{ "ttl_seconds": 3600, "table": "CoProximity" }

---

POST /v1/autocompact

Set auto-compact threshold. Requires readwrite.

{ "threshold": 1000, "table": "CoProximity" }

Tables

GET /v1/tables

List all hyperedge tables. Requires readonly.

---

GET /v1/tables/{name}

Get a single table definition. Requires readonly.

---

POST /v1/tables

Create a table. Requires admin.

{
  "name":              "Events",
  "member_tables":     ["Drone", "Host"],
  "bucket_seconds":    10,
  "compact_threshold": 1000
}

---

DELETE /v1/tables/{name}

Drop a table. Requires admin.

Indexes (PSI)

GET /v1/indexes

List PSI indexes. Requires readonly.

---

POST /v1/indexes

Create a PSI index. Requires admin.

{ "table": "CoProximity", "column": "weight" }

---

DELETE /v1/indexes/{table}/{column}

Drop a PSI index. Requires admin.

Batch (atomic)

POST /v1/batch

Execute operations atomically. All commit or all roll back. Requires readwrite.

Request:

{
  "operations": [{ "type": "insert", "event_ts": 100, "members": [1, 2] },
    { "type": "insert", "event_ts": 101, "members": [2, 3] },
    { "type": "query",  "cypher": "MATCH HYPEREDGE (he:CoProximity) RETURN *" }
  ]
}

Response 200:

{
  "committed":   true,
  "ops_total":   3,
  "ops_success": 3,
  "results": [{ "op": 0, "type": "insert", "success": true },
    { "op": 1, "type": "insert", "success": true },
    { "op": 2, "type": "query",  "success": true, "rows": [...] }
  ]
}

Analytics

POST /v1/analytics/{table}/{measure}

Compute a hypergraph analytics measure. Requires readonly.

Request:

{ "params": { "s": 2 } }

Response 200:

{
  "measure": "spectral_gap",
  "table":   "CoProximity",
  "result":  0.42
}

Supported measures: density, uniformity, overlapping_coefficient, node_degree, edge_size, isolated_nodes, isolated_edges, redundancy, betweenness, closeness, pagerank, harmonic_centrality, clique_number, spectral_gap, algebraic_connectivity, zhou_clustering, pairwise_clustering, modularity, s_adjacency, s_distance, s_connected_components, s_diameter, temporal_activity, temporal_burstiness, temporal_coreness.

Backup

POST /v1/backup

Trigger server-side backup. Requires admin.

{
  "backup_dir":    "/backups",
  "compact_first": true
}

Response 200:

{
  "path":        "/backups/hypermeshdb_20260409_120000.tar.gz",
  "size_bytes":  1048576,
  "tables":      ["CoProximity"],
  "compact_first": true
}

API Keys

GET /v1/keys

List API keys. Requires admin.

---

POST /v1/keys

Create an API key. Requires admin.

{ "role": "readwrite", "description": "ci-pipeline" }

Response 200 (plaintext key shown once only):

{
  "key_id":       "key_a3f9...",
  "description":  "ci-pipeline",
  "role":         "readwrite",
  "created_at":   1712600000,
  "plaintext_key": "hmdb_a3f9c2b1..."
}

---

DELETE /v1/keys/{key_id}

Revoke an API key. Requires admin.

Rate limiting

Responses include rate-limit headers:

X-RateLimit-Limit:     1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset:     1712600060

When the limit is exceeded, the server returns 429 Too Many Requests.

Configure with HMDB_RATE_LIMIT_QPM environment variable (default: 1000 req/min per key).

WAL

GET /v1/wal

WAL status. Requires readonly.

{ "pending": 42, "threshold": 1000 }