HeliosDB REST API Reference

Complete API Documentation for Developers and AI Bots

This reference covers all HeliosDB REST API endpoints. All endpoints use JSON for request/response bodies and require Bearer token authentication.

Base URL

Production: https://api.heliosdb.io/v1
Database:   https://{database-name}.heliosdb.io/api/v1

Authentication

All API requests require a Bearer token in the Authorization header:

curl -X GET https://api.heliosdb.io/v1/databases \
  -H "Authorization: Bearer hdb_live_xxxxxxxxxxxx"

See Authentication Guide for token management.

Response Format

All responses follow this structure:

{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "req_xxxxxxxxxxxx",
    "duration_ms": 12,
    "timestamp": "2025-12-16T00:00:00Z"
  }
}

Error responses:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": { ... }
  },
  "meta": { ... }
}

Authentication Endpoints

POST /auth/signup

Create a new account.

curl -X POST https://api.heliosdb.io/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure-password-123"
  }'

Response:

{
  "success": true,
  "data": {
    "user_id": "usr_xxxxxxxxxxxx",
    "email": "user@example.com",
    "verification_sent": true
  }
}

POST /auth/login

Authenticate and receive a token.

curl -X POST https://api.heliosdb.io/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure-password-123"
  }'

Response:

{
  "success": true,
  "data": {
    "token": "hdb_live_xxxxxxxxxxxx",
    "token_type": "bearer",
    "expires_at": "2025-12-23T00:00:00Z",
    "user": {
      "id": "usr_xxxxxxxxxxxx",
      "email": "user@example.com"
    }
  }
}

POST /auth/refresh

Refresh an expiring token.

curl -X POST https://api.heliosdb.io/v1/auth/refresh \
  -H "Authorization: Bearer hdb_live_xxxxxxxxxxxx"

POST /auth/logout

Invalidate the current token.

curl -X POST https://api.heliosdb.io/v1/auth/logout \
  -H "Authorization: Bearer hdb_live_xxxxxxxxxxxx"

Database Endpoints

POST /databases

Create a new database.

curl -X POST https://api.heliosdb.io/v1/databases \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app-db",
    "tier": "free",
    "region": "us-east-1"
  }'

Parameters:

Field	Type	Required	Description
name	string	Yes	Database name (alphanumeric, hyphens)
tier	string	Yes	`free`, `developer`, `team`, `enterprise`
region	string	No	Region code (default: `us-east-1`)

Response:

{
  "success": true,
  "data": {
    "id": "db_xxxxxxxxxxxx",
    "name": "my-app-db",
    "tier": "free",
    "region": "us-east-1",
    "status": "provisioning",
    "endpoints": {
      "postgresql": "my-app-db.heliosdb.io:5432",
      "mysql": "my-app-db.heliosdb.io:3306",
      "mongodb": "my-app-db.heliosdb.io:27017",
      "redis": "my-app-db.heliosdb.io:6379",
      "rest": "https://my-app-db.heliosdb.io/api/v1"
    },
    "created_at": "2025-12-16T00:00:00Z"
  }
}

GET /databases

List all databases.

curl -X GET https://api.heliosdb.io/v1/databases \
  -H "Authorization: Bearer $HELIOS_TOKEN"

GET /databases/{id}

Get database details.

curl -X GET https://api.heliosdb.io/v1/databases/db_xxxxxxxxxxxx \
  -H "Authorization: Bearer $HELIOS_TOKEN"

DELETE /databases/{id}

Delete a database.

curl -X DELETE https://api.heliosdb.io/v1/databases/db_xxxxxxxxxxxx \
  -H "Authorization: Bearer $HELIOS_TOKEN"

SQL Endpoints

POST /sql

Execute a SQL query.

curl -X POST https://my-app-db.heliosdb.io/api/v1/sql \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM users WHERE status = $1 LIMIT $2",
    "params": ["active", 10]
  }'

Parameters:

Field	Type	Required	Description
query	string	Yes	SQL query with $1, $2… placeholders
params	array	No	Positional parameters
timeout	integer	No	Query timeout in ms (default: 30000)
branch	string	No	Branch to query (default: main)

Response (SELECT):

{
  "success": true,
  "data": {
    "columns": ["id", "name", "email", "status"],
    "rows": [
      ["usr_001", "Alice", "alice@example.com", "active"],
      ["usr_002", "Bob", "bob@example.com", "active"]
    ],
    "row_count": 2
  },
  "meta": {
    "duration_ms": 5,
    "rows_examined": 1000
  }
}

Response (INSERT/UPDATE/DELETE):

{
  "success": true,
  "data": {
    "affected_rows": 1,
    "returning": [
      {"id": "usr_003", "name": "Charlie", "email": "charlie@example.com"}
    ]
  }
}

POST /sql/batch

Execute multiple SQL statements in a transaction.

curl -X POST https://my-app-db.heliosdb.io/api/v1/sql/batch \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "statements": [
      {"query": "INSERT INTO orders (user_id, total) VALUES ($1, $2) RETURNING id", "params": ["usr_001", 99.99]},
      {"query": "UPDATE users SET last_order_at = NOW() WHERE id = $1", "params": ["usr_001"]}
    ],
    "transaction": true
  }'

POST /sql/explain

Get query execution plan.

curl -X POST https://my-app-db.heliosdb.io/api/v1/sql/explain \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM orders WHERE user_id = $1",
    "params": ["usr_001"],
    "analyze": true
  }'

Branch Endpoints

POST /branches

Create a database branch.

curl -X POST https://my-app-db.heliosdb.io/api/v1/branches \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "feature/user-auth",
    "from": "main"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "br_xxxxxxxxxxxx",
    "name": "feature/user-auth",
    "parent": "main",
    "created_at": "2025-12-16T00:00:00Z",
    "creation_time_us": 555
  }
}

GET /branches

List all branches.

curl -X GET https://my-app-db.heliosdb.io/api/v1/branches \
  -H "Authorization: Bearer $HELIOS_TOKEN"

POST /branches/merge

Merge a branch.

curl -X POST https://my-app-db.heliosdb.io/api/v1/branches/merge \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "feature/user-auth",
    "target": "main",
    "strategy": "fast-forward"
  }'

DELETE /branches/{name}

Delete a branch.

curl -X DELETE https://my-app-db.heliosdb.io/api/v1/branches/feature%2Fuser-auth \
  -H "Authorization: Bearer $HELIOS_TOKEN"

Schema Endpoints

GET /schema/tables

List all tables.

curl -X GET https://my-app-db.heliosdb.io/api/v1/schema/tables \
  -H "Authorization: Bearer $HELIOS_TOKEN"

Response:

{
  "success": true,
  "data": {
    "tables": [
      {
        "name": "users",
        "columns": [
          {"name": "id", "type": "uuid", "nullable": false, "primary_key": true},
          {"name": "email", "type": "text", "nullable": false, "unique": true},
          {"name": "created_at", "type": "timestamptz", "nullable": false}
        ],
        "indexes": ["users_pkey", "users_email_key"],
        "row_count_estimate": 10000
      }
    ]
  }
}

POST /schema/generate

Generate schema from natural language.

curl -X POST https://my-app-db.heliosdb.io/api/v1/schema/generate \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "E-commerce platform with users, products, orders, and reviews. Support for product variants and inventory tracking.",
    "dialect": "postgresql"
  }'

Response:

{
  "success": true,
  "data": {
    "tables": [
      {
        "name": "users",
        "ddl": "CREATE TABLE users (...)",
        "columns": [...]
      }
    ],
    "relationships": [
      {"from": "orders.user_id", "to": "users.id", "type": "many-to-one"}
    ],
    "indexes": [...],
    "capacity_forecast": {
      "30_days": "50MB",
      "90_days": "150MB",
      "365_days": "600MB"
    }
  }
}

Vector/AI Endpoints

POST /vectors/embed

Generate embeddings.

curl -X POST https://my-app-db.heliosdb.io/api/v1/vectors/embed \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "texts": ["Hello world", "How are you?"],
    "model": "openai/text-embedding-3-small"
  }'

Response:

{
  "success": true,
  "data": {
    "embeddings": [
      [0.123, -0.456, ...],
      [0.789, -0.012, ...]
    ],
    "model": "openai/text-embedding-3-small",
    "dimensions": 1536
  }
}

POST /vectors/search

Semantic vector search.

curl -X POST https://my-app-db.heliosdb.io/api/v1/vectors/search \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "table": "documents",
    "embedding_column": "embedding",
    "query": "how to authenticate users",
    "limit": 10,
    "threshold": 0.7
  }'

Response:

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "doc_001",
        "content": "User authentication guide...",
        "similarity": 0.92
      }
    ]
  }
}

Codegen Endpoints

POST /codegen/rest

Generate REST API for tables.

curl -X POST https://my-app-db.heliosdb.io/api/v1/codegen/rest \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tables": ["users", "orders"],
    "operations": ["create", "read", "update", "delete", "list"],
    "authentication": "bearer"
  }'

POST /codegen/graphql

Generate GraphQL schema.

curl -X POST https://my-app-db.heliosdb.io/api/v1/codegen/graphql \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tables": ["users", "orders", "products"],
    "include_mutations": true,
    "include_subscriptions": true
  }'

POST /codegen/types

Generate type definitions.

curl -X POST https://my-app-db.heliosdb.io/api/v1/codegen/types \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tables": ["users", "orders"],
    "language": "typescript"
  }'

Response:

{
  "success": true,
  "data": {
    "typescript": "export interface User {\n  id: string;\n  email: string;\n  created_at: Date;\n}\n\nexport interface Order {\n  id: string;\n  user_id: string;\n  total: number;\n  status: string;\n}"
  }
}

Metrics Endpoints

GET /metrics/usage

Get usage metrics.

curl -X GET https://my-app-db.heliosdb.io/api/v1/metrics/usage \
  -H "Authorization: Bearer $HELIOS_TOKEN"

Response:

{
  "success": true,
  "data": {
    "period": "current_month",
    "storage_bytes": 52428800,
    "queries_executed": 45678,
    "compute_seconds": 3600,
    "api_calls": 12345,
    "branches_active": 3
  }
}

GET /metrics/performance

Get performance metrics.

curl -X GET https://my-app-db.heliosdb.io/api/v1/metrics/performance?period=24h \
  -H "Authorization: Bearer $HELIOS_TOKEN"

Rate Limits

Tier	Requests/minute	Queries/minute
Free	100	60
Developer	1,000	600
Team	10,000	6,000
Enterprise	Unlimited	Unlimited

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1734307200

Error Codes

Code	HTTP Status	Description
AUTH_REQUIRED	401	Missing or invalid token
AUTH_EXPIRED	401	Token has expired
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Invalid request parameters
RATE_LIMITED	429	Too many requests
QUERY_ERROR	400	SQL syntax or execution error
QUOTA_EXCEEDED	402	Plan limits exceeded
SERVER_ERROR	500	Internal error

SDKs and Libraries

Official SDKs:

Community SDKs:

Webhook Events

Configure webhooks for real-time notifications:

curl -X POST https://api.heliosdb.io/v1/webhooks \
  -H "Authorization: Bearer $HELIOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/helios",
    "events": ["database.created", "branch.merged", "query.slow"],
    "secret": "your-webhook-secret"
  }'

Event types:

database.created, database.deleted
branch.created, branch.merged, branch.deleted
query.slow (queries exceeding threshold)
usage.threshold (approaching plan limits)

For additional help, visit docs.heliosdb.io or contact support@heliosdb.io