HeliosDB HTTP/REST API Reference

Version: 7.0 Last Updated: January 2026

Complete reference documentation for HeliosDB’s HTTP/REST API, including all endpoints, request/response formats, error handling, and best practices.

Base Configuration
Query Endpoints
Table Management
Row Operations (CRUD)
Transaction Endpoints
Vector Operations
Admin Endpoints
Error Handling
Rate Limiting
Pagination

Base Configuration

Base URLs

Environment	URL	Port
Production HTTPS	`https://api.heliosdb.io/api/v1`	443
Production HTTP	`http://api.heliosdb.io/api/v1`	8080
Local Development	`http://localhost:8080/api/v1`	8080
Docker Default	`http://heliosdb:8080/api/v1`	8080

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token or API key
`Content-Type`	Yes (POST/PUT)	`application/json`
`Accept`	No	Response format: `application/json`, `application/x-ndjson`
`X-Request-ID`	No	Client-generated request ID for tracing
`X-Tenant-ID`	No	Tenant identifier for multi-tenancy

Authentication

API Key (Recommended for services):

curl -H "Authorization: Bearer hdb_sk_your_api_key" \
     https://api.heliosdb.io/api/v1/tables

Alternative API Key Header:

curl -H "X-API-Key: hdb_sk_your_api_key" \
     https://api.heliosdb.io/api/v1/tables

JWT Token (For user sessions):

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
     https://api.heliosdb.io/api/v1/tables

Query Endpoints

Execute SQL Query

Execute a SQL query and return results.

Endpoint: POST /query

Request Body:

{
  "sql": "SELECT * FROM users WHERE status = $1 AND age > $2 LIMIT $3",
  "params": ["active", 21, 100],
  "timeout_ms": 30000,
  "include_metadata": true
}

Parameters:

Field	Type	Required	Description
`sql`	string	Yes	SQL query to execute
`params`	array	No	Positional parameters ($1, $2, etc.)
`timeout_ms`	integer	No	Query timeout in milliseconds (default: 30000)
`include_metadata`	boolean	No	Include column metadata (default: false)
`max_rows`	integer	No	Maximum rows to return (default: 10000)

Response (200 OK):

{
  "success": true,
  "data": [
    {"id": 1, "name": "Alice", "email": "alice@example.com", "age": 25},
    {"id": 2, "name": "Bob", "email": "bob@example.com", "age": 30}
  ],
  "metadata": {
    "columns": [
      {"name": "id", "type": "BIGINT", "nullable": false},
      {"name": "name", "type": "VARCHAR", "nullable": false},
      {"name": "email", "type": "VARCHAR", "nullable": false},
      {"name": "age", "type": "INTEGER", "nullable": true}
    ],
    "row_count": 2,
    "execution_time_ms": 12,
    "query_id": "q_abc123"
  }
}

Example:

curl -X POST https://api.heliosdb.io/api/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT id, name, email FROM users WHERE status = $1 ORDER BY created_at DESC LIMIT 10",
    "params": ["active"]
  }'

Execute Async Query

Execute a long-running query asynchronously.

Endpoint: POST /query/async

Request Body:

{
  "sql": "SELECT customer_id, SUM(amount) as total FROM orders GROUP BY customer_id",
  "params": [],
  "timeout_ms": 300000,
  "callback_url": "https://your-app.com/webhook/query-complete"
}

Response (202 Accepted):

{
  "query_id": "async_q_xyz789",
  "status": "pending",
  "status_url": "/api/v1/query/async_q_xyz789",
  "estimated_time_ms": 45000
}

Get Async Query Status

Check the status of an async query.

Endpoint: GET /query/{query_id}

Response (Running):

{
  "query_id": "async_q_xyz789",
  "status": "running",
  "progress": 45,
  "started_at": "2026-01-04T12:00:00Z"
}

Response (Completed):

{
  "query_id": "async_q_xyz789",
  "status": "completed",
  "data": [...],
  "metadata": {
    "row_count": 15234,
    "execution_time_ms": 42150
  },
  "started_at": "2026-01-04T12:00:00Z",
  "completed_at": "2026-01-04T12:00:42Z"
}

Response (Failed):

{
  "query_id": "async_q_xyz789",
  "status": "failed",
  "error": {
    "code": "QUERY_TIMEOUT",
    "message": "Query exceeded maximum execution time"
  }
}

Stream Query Results

Stream query results as newline-delimited JSON (NDJSON).

Endpoint: POST /query/stream

Headers:

Accept: application/x-ndjson

Request Body:

{
  "sql": "SELECT * FROM large_table",
  "batch_size": 1000
}

Response (Streaming):

{"id":1,"name":"Alice","email":"alice@example.com"}
{"id":2,"name":"Bob","email":"bob@example.com"}
{"id":3,"name":"Charlie","email":"charlie@example.com"}
...

Python Example:

import requests

response = requests.post(
    "https://api.heliosdb.io/api/v1/query/stream",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
        "Accept": "application/x-ndjson"
    },
    json={"sql": "SELECT * FROM events WHERE date > '2025-01-01'"},
    stream=True
)

for line in response.iter_lines():
    if line:
        row = json.loads(line)
        process_row(row)

Cancel Query

Cancel a running query.

Endpoint: DELETE /query/{query_id}

Response (200 OK):

{
  "query_id": "async_q_xyz789",
  "status": "cancelled",
  "cancelled_at": "2026-01-04T12:01:00Z"
}

Explain Query

Get the query execution plan without running the query.

Endpoint: POST /query/explain

Request Body:

{
  "sql": "SELECT * FROM users WHERE email = $1",
  "params": ["test@example.com"],
  "analyze": false,
  "format": "json"
}

Parameters:

Field	Type	Description
`analyze`	boolean	Execute query to get actual timings (default: false)
`format`	string	Output format: `text`, `json`, `yaml` (default: json)

Response (200 OK):

{
  "plan": {
    "node_type": "Index Scan",
    "index_name": "idx_users_email",
    "relation": "users",
    "index_cond": "(email = 'test@example.com')",
    "estimated_rows": 1,
    "estimated_cost": 0.29,
    "actual_rows": null,
    "actual_time_ms": null
  },
  "planning_time_ms": 0.5
}

Table Management

List Tables

Get a list of all tables in the database.

Endpoint: GET /tables

Query Parameters:

Parameter	Type	Description
`schema`	string	Filter by schema name
`pattern`	string	Filter by name pattern (SQL LIKE)
`include_views`	boolean	Include views (default: true)
`include_system`	boolean	Include system tables (default: false)

Response (200 OK):

{
  "tables": [
    {
      "name": "users",
      "schema": "public",
      "type": "table",
      "row_count": 150000,
      "size_bytes": 45000000,
      "created_at": "2025-06-01T10:00:00Z",
      "updated_at": "2026-01-04T08:00:00Z"
    },
    {
      "name": "orders",
      "schema": "public",
      "type": "table",
      "row_count": 2500000,
      "size_bytes": 890000000,
      "created_at": "2025-06-01T10:00:00Z",
      "updated_at": "2026-01-04T11:30:00Z"
    },
    {
      "name": "user_stats",
      "schema": "public",
      "type": "materialized_view",
      "row_count": 150000,
      "size_bytes": 12000000,
      "created_at": "2025-08-15T14:00:00Z",
      "updated_at": "2026-01-04T06:00:00Z"
    }
  ],
  "total_count": 3
}

Get Table Schema

Get detailed schema information for a specific table.

Endpoint: GET /tables/{table_name}

Response (200 OK):

{
  "name": "users",
  "schema": "public",
  "type": "table",
  "columns": [
    {
      "name": "id",
      "type": "BIGINT",
      "nullable": false,
      "default": "nextval('users_id_seq'::regclass)",
      "is_primary_key": true
    },
    {
      "name": "email",
      "type": "VARCHAR(255)",
      "nullable": false,
      "default": null,
      "is_primary_key": false
    },
    {
      "name": "name",
      "type": "VARCHAR(255)",
      "nullable": false,
      "default": null,
      "is_primary_key": false
    },
    {
      "name": "age",
      "type": "INTEGER",
      "nullable": true,
      "default": null,
      "is_primary_key": false
    },
    {
      "name": "status",
      "type": "VARCHAR(50)",
      "nullable": false,
      "default": "'active'",
      "is_primary_key": false
    },
    {
      "name": "created_at",
      "type": "TIMESTAMP WITH TIME ZONE",
      "nullable": false,
      "default": "now()",
      "is_primary_key": false
    },
    {
      "name": "embedding",
      "type": "VECTOR(1536)",
      "nullable": true,
      "default": null,
      "is_primary_key": false
    }
  ],
  "indexes": [
    {
      "name": "users_pkey",
      "type": "btree",
      "columns": ["id"],
      "unique": true,
      "primary": true
    },
    {
      "name": "idx_users_email",
      "type": "btree",
      "columns": ["email"],
      "unique": true,
      "primary": false
    },
    {
      "name": "idx_users_status",
      "type": "btree",
      "columns": ["status"],
      "unique": false,
      "primary": false
    },
    {
      "name": "idx_users_embedding",
      "type": "hnsw",
      "columns": ["embedding"],
      "unique": false,
      "primary": false,
      "options": {"m": 16, "ef_construction": 64}
    }
  ],
  "constraints": [
    {
      "name": "users_status_check",
      "type": "check",
      "definition": "status IN ('active', 'inactive', 'suspended')"
    }
  ],
  "statistics": {
    "row_count": 150000,
    "size_bytes": 45000000,
    "index_size_bytes": 12000000,
    "last_analyzed": "2026-01-04T06:00:00Z"
  }
}

Create Table

Create a new table.

Endpoint: POST /tables

Request Body:

{
  "name": "products",
  "schema": "public",
  "columns": [
    {
      "name": "id",
      "type": "BIGSERIAL",
      "nullable": false,
      "primary_key": true
    },
    {
      "name": "sku",
      "type": "VARCHAR(50)",
      "nullable": false
    },
    {
      "name": "name",
      "type": "VARCHAR(255)",
      "nullable": false
    },
    {
      "name": "description",
      "type": "TEXT",
      "nullable": true
    },
    {
      "name": "price",
      "type": "DECIMAL(10,2)",
      "nullable": false,
      "check": "price >= 0"
    },
    {
      "name": "inventory",
      "type": "INTEGER",
      "nullable": false,
      "default": "0"
    },
    {
      "name": "category",
      "type": "VARCHAR(100)",
      "nullable": true
    },
    {
      "name": "embedding",
      "type": "VECTOR(768)",
      "nullable": true
    },
    {
      "name": "metadata",
      "type": "JSONB",
      "nullable": true
    },
    {
      "name": "created_at",
      "type": "TIMESTAMP WITH TIME ZONE",
      "nullable": false,
      "default": "NOW()"
    }
  ],
  "indexes": [
    {
      "name": "idx_products_sku",
      "columns": ["sku"],
      "unique": true
    },
    {
      "name": "idx_products_category",
      "columns": ["category"]
    },
    {
      "name": "idx_products_embedding",
      "columns": ["embedding"],
      "type": "hnsw",
      "options": {"m": 16, "ef_construction": 64}
    }
  ],
  "if_not_exists": true
}

Response (201 Created):

{
  "success": true,
  "table": {
    "name": "products",
    "schema": "public",
    "created_at": "2026-01-04T12:00:00Z"
  }
}

Alter Table

Modify an existing table structure.

Endpoint: PATCH /tables/{table_name}

Request Body:

{
  "operations": [
    {
      "operation": "add_column",
      "column": {
        "name": "discount_percent",
        "type": "DECIMAL(5,2)",
        "nullable": true,
        "default": "0"
      }
    },
    {
      "operation": "drop_column",
      "column_name": "old_field"
    },
    {
      "operation": "rename_column",
      "old_name": "desc",
      "new_name": "description"
    },
    {
      "operation": "add_index",
      "index": {
        "name": "idx_products_price",
        "columns": ["price"]
      }
    }
  ]
}

Response (200 OK):

{
  "success": true,
  "operations_completed": 4,
  "table": {
    "name": "products",
    "updated_at": "2026-01-04T12:05:00Z"
  }
}

Drop Table

Delete a table.

Endpoint: DELETE /tables/{table_name}

Query Parameters:

Parameter	Type	Description
`cascade`	boolean	Drop dependent objects (default: false)
`if_exists`	boolean	Don’t error if table doesn’t exist (default: false)

Response (200 OK):

{
  "success": true,
  "table": "products",
  "dropped_at": "2026-01-04T12:10:00Z"
}

Row Operations (CRUD)

Read Rows

Query rows from a table with filtering, sorting, and pagination.

Endpoint: GET /tables/{table_name}/rows

Query Parameters:

Parameter	Type	Description
`filter`	string	WHERE clause filter (e.g., `status='active'`)
`select`	string	Columns to select (comma-separated)
`order_by`	string	Sort column (prefix with `-` for DESC)
`limit`	integer	Maximum rows (default: 100, max: 10000)
`offset`	integer	Offset for pagination
`cursor`	string	Cursor for cursor-based pagination

Example Request:

curl "https://api.heliosdb.io/api/v1/tables/users/rows?filter=status='active'&select=id,name,email&order_by=-created_at&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK):

{
  "data": [
    {"id": 150, "name": "Zoe", "email": "zoe@example.com"},
    {"id": 149, "name": "Yolanda", "email": "yolanda@example.com"},
    {"id": 148, "name": "Xavier", "email": "xavier@example.com"}
  ],
  "pagination": {
    "total_count": 1250,
    "limit": 25,
    "offset": 0,
    "has_more": true,
    "next_cursor": "eyJpZCI6MTQ3fQ=="
  }
}

Insert Rows

Insert one or more rows into a table.

Endpoint: POST /tables/{table_name}/rows

Request Body (Single Row):

{
  "row": {
    "name": "Alice Johnson",
    "email": "alice.johnson@example.com",
    "age": 28,
    "status": "active"
  },
  "returning": ["id", "created_at"]
}

Request Body (Bulk Insert):

{
  "rows": [
    {"name": "Bob Smith", "email": "bob@example.com", "age": 35},
    {"name": "Carol White", "email": "carol@example.com", "age": 29},
    {"name": "David Brown", "email": "david@example.com", "age": 42}
  ],
  "on_conflict": {
    "columns": ["email"],
    "action": "update",
    "update_columns": ["name", "age"]
  },
  "returning": ["id"]
}

Parameters:

Field	Type	Description
`row`	object	Single row to insert
`rows`	array	Multiple rows to insert
`returning`	array	Columns to return after insert
`on_conflict`	object	Upsert behavior on conflict

Response (201 Created):

{
  "success": true,
  "inserted_count": 3,
  "data": [
    {"id": 151},
    {"id": 152},
    {"id": 153}
  ]
}

Update Rows

Update rows matching a filter.

Endpoint: PUT /tables/{table_name}/rows

Request Body:

{
  "filter": "status = 'pending' AND created_at < '2025-12-01'",
  "updates": {
    "status": "expired",
    "updated_at": "2026-01-04T12:00:00Z"
  },
  "returning": ["id", "status"]
}

Response (200 OK):

{
  "success": true,
  "affected_rows": 47,
  "data": [
    {"id": 23, "status": "expired"},
    {"id": 45, "status": "expired"},
    {"id": 67, "status": "expired"}
  ]
}

Delete Rows

Delete rows matching a filter.

Endpoint: DELETE /tables/{table_name}/rows

Request Body:

{
  "filter": "status = 'deleted' AND deleted_at < '2025-01-01'",
  "returning": ["id"]
}

Response (200 OK):

{
  "success": true,
  "deleted_count": 156,
  "data": [
    {"id": 10},
    {"id": 15},
    {"id": 22}
  ]
}

Get Row by ID

Get a single row by primary key.

Endpoint: GET /tables/{table_name}/rows/{id}

Response (200 OK):

{
  "data": {
    "id": 123,
    "name": "Alice",
    "email": "alice@example.com",
    "age": 28,
    "status": "active",
    "created_at": "2025-06-15T10:30:00Z"
  }
}

Update Row by ID

Update a single row by primary key.

Endpoint: PATCH /tables/{table_name}/rows/{id}

Request Body:

{
  "updates": {
    "name": "Alice Smith",
    "age": 29
  },
  "returning": ["id", "name", "age", "updated_at"]
}

Response (200 OK):

{
  "success": true,
  "data": {
    "id": 123,
    "name": "Alice Smith",
    "age": 29,
    "updated_at": "2026-01-04T12:15:00Z"
  }
}

Delete Row by ID

Delete a single row by primary key.

Endpoint: DELETE /tables/{table_name}/rows/{id}

Response (200 OK):

{
  "success": true,
  "deleted": true
}

Transaction Endpoints

Begin Transaction

Start a new transaction.

Endpoint: POST /transactions

Request Body:

{
  "isolation_level": "serializable",
  "timeout_ms": 30000,
  "read_only": false
}

Parameters:

Field	Type	Description
`isolation_level`	string	`read_committed`, `repeatable_read`, `serializable`
`timeout_ms`	integer	Transaction timeout
`read_only`	boolean	Read-only transaction

Response (201 Created):

{
  "transaction_id": "txn_abc123xyz",
  "isolation_level": "serializable",
  "started_at": "2026-01-04T12:00:00Z",
  "expires_at": "2026-01-04T12:00:30Z"
}

Execute in Transaction

Execute a query within a transaction.

Endpoint: POST /transactions/{transaction_id}/query

Request Body:

{
  "sql": "UPDATE accounts SET balance = balance - $1 WHERE id = $2",
  "params": [100.00, 1]
}

Response (200 OK):

{
  "success": true,
  "affected_rows": 1,
  "transaction_id": "txn_abc123xyz"
}

Commit Transaction

Commit a transaction.

Endpoint: POST /transactions/{transaction_id}/commit

Response (200 OK):

{
  "success": true,
  "transaction_id": "txn_abc123xyz",
  "committed_at": "2026-01-04T12:00:15Z"
}

Rollback Transaction

Rollback a transaction.

Endpoint: POST /transactions/{transaction_id}/rollback

Response (200 OK):

{
  "success": true,
  "transaction_id": "txn_abc123xyz",
  "rolled_back_at": "2026-01-04T12:00:10Z"
}

Vector Operations

Vector Search

Perform similarity search on vector embeddings.

Endpoint: POST /vectors/search

Request Body:

{
  "index": "documents_embedding_idx",
  "vector": [0.1, 0.2, 0.3, 0.4, ...],
  "top_k": 10,
  "filter": "category = 'technology'",
  "include_vectors": false,
  "include_metadata": true,
  "metric": "cosine",
  "ef_search": 100
}

Parameters:

Field	Type	Description
`index`	string	Vector index name
`vector`	array	Query vector
`top_k`	integer	Number of results (default: 10)
`filter`	string	SQL filter condition
`include_vectors`	boolean	Return vectors in results
`include_metadata`	boolean	Return metadata columns
`metric`	string	Distance metric: `cosine`, `l2`, `inner_product`
`ef_search`	integer	HNSW search parameter (higher = better quality)

Response (200 OK):

{
  "results": [
    {
      "id": 456,
      "score": 0.92,
      "distance": 0.08,
      "metadata": {
        "title": "Introduction to Machine Learning",
        "category": "technology",
        "author": "Jane Doe"
      }
    },
    {
      "id": 789,
      "score": 0.88,
      "distance": 0.12,
      "metadata": {
        "title": "Deep Learning Fundamentals",
        "category": "technology",
        "author": "John Smith"
      }
    }
  ],
  "query_time_ms": 15
}

Upsert Vectors

Insert or update vectors with metadata.

Endpoint: POST /vectors/upsert

Request Body:

{
  "table": "documents",
  "vectors": [
    {
      "id": "doc_001",
      "vector": [0.1, 0.2, 0.3, ...],
      "metadata": {
        "title": "Document One",
        "category": "science",
        "created_at": "2026-01-04T12:00:00Z"
      }
    },
    {
      "id": "doc_002",
      "vector": [0.4, 0.5, 0.6, ...],
      "metadata": {
        "title": "Document Two",
        "category": "technology",
        "created_at": "2026-01-04T12:01:00Z"
      }
    }
  ]
}

Response (200 OK):

{
  "success": true,
  "upserted_count": 2,
  "ids": ["doc_001", "doc_002"]
}

Delete Vectors

Delete vectors by ID or filter.

Endpoint: DELETE /vectors

Request Body:

{
  "table": "documents",
  "ids": ["doc_001", "doc_002"],
  "filter": null
}

Alternative - Delete by Filter:

{
  "table": "documents",
  "ids": null,
  "filter": "category = 'deprecated'"
}

Response (200 OK):

{
  "success": true,
  "deleted_count": 2
}

Admin Endpoints

Health Check

Check server health status.

Endpoint: GET /health

Response (200 OK):

{
  "status": "healthy",
  "version": "7.0.0",
  "uptime_seconds": 864000,
  "components": {
    "storage": "healthy",
    "query_engine": "healthy",
    "replication": "healthy",
    "cache": "healthy"
  }
}

Readiness Check

Check if server is ready to accept requests.

Endpoint: GET /ready

Response (200 OK):

{
  "ready": true,
  "checks": {
    "database": true,
    "connections_available": true,
    "replication_synced": true
  }
}

Liveness Check

Check if server is alive (for Kubernetes probes).

Endpoint: GET /live

Response (200 OK):

{
  "alive": true
}

Server Info

Get server information and capabilities.

Endpoint: GET /info

Response (200 OK):

{
  "version": "7.0.0",
  "build": "2026.01.04-abc123",
  "api_version": "v1",
  "features": {
    "vector_search": true,
    "graph_queries": true,
    "time_series": true,
    "multi_tenancy": true,
    "streaming": true
  },
  "protocols": ["postgresql", "mongodb", "redis", "cassandra", "http", "grpc"],
  "limits": {
    "max_query_size_bytes": 1048576,
    "max_result_rows": 100000,
    "max_connections": 10000
  }
}

Prometheus Metrics

Get Prometheus-format metrics.

Endpoint: GET /metrics

Response (200 OK):

# HELP heliosdb_queries_total Total number of queries executed
# TYPE heliosdb_queries_total counter
heliosdb_queries_total{status="success"} 1234567
heliosdb_queries_total{status="error"} 123

# HELP heliosdb_query_duration_seconds Query execution duration
# TYPE heliosdb_query_duration_seconds histogram
heliosdb_query_duration_seconds_bucket{le="0.01"} 500000
heliosdb_query_duration_seconds_bucket{le="0.1"} 1100000
heliosdb_query_duration_seconds_bucket{le="1.0"} 1200000
heliosdb_query_duration_seconds_bucket{le="+Inf"} 1234567

# HELP heliosdb_connections_active Active database connections
# TYPE heliosdb_connections_active gauge
heliosdb_connections_active 250

# HELP heliosdb_cache_hit_ratio Cache hit ratio
# TYPE heliosdb_cache_hit_ratio gauge
heliosdb_cache_hit_ratio 0.95

Error Handling

Error Response Format

All errors follow a consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "additional context"
    },
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

Code	Meaning	When Used
200	OK	Successful request
201	Created	Resource created
202	Accepted	Async operation started
204	No Content	Successful with no response body
400	Bad Request	Invalid request syntax or parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Authenticated but not authorized
404	Not Found	Resource does not exist
409	Conflict	Resource conflict (e.g., duplicate key)
422	Unprocessable Entity	Validation error
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error
503	Service Unavailable	Server temporarily unavailable

Common Error Codes

Code	Description
`AUTHENTICATION_REQUIRED`	No authentication provided
`AUTHENTICATION_FAILED`	Invalid credentials
`AUTHORIZATION_DENIED`	Insufficient permissions
`INVALID_QUERY`	SQL syntax error
`TABLE_NOT_FOUND`	Referenced table does not exist
`COLUMN_NOT_FOUND`	Referenced column does not exist
`CONSTRAINT_VIOLATION`	Unique/foreign key violation
`TYPE_MISMATCH`	Data type mismatch
`QUERY_TIMEOUT`	Query exceeded time limit
`RATE_LIMIT_EXCEEDED`	Too many requests
`TRANSACTION_CONFLICT`	Serialization failure
`INTERNAL_ERROR`	Unexpected server error

Rate Limiting

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1704364800
X-RateLimit-Reset-After: 3600

Rate Limit Response (429)

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "details": {
      "limit": 1000,
      "remaining": 0,
      "reset_at": "2026-01-04T13:00:00Z"
    }
  }
}

Pagination

Offset-Based Pagination

# Page 1
GET /tables/users/rows?limit=25&offset=0

# Page 2
GET /tables/users/rows?limit=25&offset=25

# Page 3
GET /tables/users/rows?limit=25&offset=50

Cursor-Based Pagination (Recommended)

# First page
GET /tables/users/rows?limit=25

# Subsequent pages using cursor from response
GET /tables/users/rows?limit=25&cursor=eyJpZCI6MjV9

Response with Pagination:

{
  "data": [...],
  "pagination": {
    "limit": 25,
    "total_count": 1250,
    "has_more": true,
    "next_cursor": "eyJpZCI6NTB9",
    "prev_cursor": "eyJpZCI6MjV9"
  }
}

Best Practices

Use cursor pagination for large datasets (more efficient)
Set reasonable limits (25-100 rows per page)
Cache total_count if needed frequently
Use streaming for very large exports

SDK Examples

Python

import requests
from typing import Optional, Dict, Any, List

class HeliosDBClient:
    def __init__(self, base_url: str, api_key: str):
        self.base_url = base_url.rstrip('/')
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }

    def query(self, sql: str, params: Optional[List] = None) -> Dict[str, Any]:
        response = requests.post(
            f'{self.base_url}/query',
            headers=self.headers,
            json={'sql': sql, 'params': params or []}
        )
        response.raise_for_status()
        return response.json()

    def insert(self, table: str, rows: List[Dict]) -> Dict[str, Any]:
        response = requests.post(
            f'{self.base_url}/tables/{table}/rows',
            headers=self.headers,
            json={'rows': rows}
        )
        response.raise_for_status()
        return response.json()

    def vector_search(self, index: str, vector: List[float], top_k: int = 10) -> Dict[str, Any]:
        response = requests.post(
            f'{self.base_url}/vectors/search',
            headers=self.headers,
            json={'index': index, 'vector': vector, 'top_k': top_k}
        )
        response.raise_for_status()
        return response.json()

# Usage
client = HeliosDBClient('https://api.heliosdb.io/api/v1', 'YOUR_API_KEY')

# Query
result = client.query('SELECT * FROM users WHERE status = $1', ['active'])
print(result['data'])

# Insert
client.insert('users', [
    {'name': 'Alice', 'email': 'alice@example.com'},
    {'name': 'Bob', 'email': 'bob@example.com'}
])

# Vector search
matches = client.vector_search('documents_idx', [0.1, 0.2, 0.3, ...])
print(matches['results'])

JavaScript/TypeScript

interface QueryResult {
  data: Record<string, any>[];
  metadata?: {
    row_count: number;
    execution_time_ms: number;
  };
}

class HeliosDBClient {
  private baseUrl: string;
  private headers: HeadersInit;

  constructor(baseUrl: string, apiKey: string) {
    this.baseUrl = baseUrl.replace(/\/$/, '');
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    };
  }

  async query(sql: string, params: any[] = []): Promise<QueryResult> {
    const response = await fetch(`${this.baseUrl}/query`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({ sql, params })
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error.message);
    }

    return response.json();
  }

  async insert(table: string, rows: Record<string, any>[]): Promise<any> {
    const response = await fetch(`${this.baseUrl}/tables/${table}/rows`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({ rows })
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error.message);
    }

    return response.json();
  }

  async vectorSearch(index: string, vector: number[], topK = 10): Promise<any> {
    const response = await fetch(`${this.baseUrl}/vectors/search`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify({ index, vector, top_k: topK })
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error.message);
    }

    return response.json();
  }
}

// Usage
const client = new HeliosDBClient('https://api.heliosdb.io/api/v1', 'YOUR_API_KEY');

// Query
const result = await client.query('SELECT * FROM users WHERE status = $1', ['active']);
console.log(result.data);

// Insert
await client.insert('users', [
  { name: 'Alice', email: 'alice@example.com' },
  { name: 'Bob', email: 'bob@example.com' }
]);

// Vector search
const matches = await client.vectorSearch('documents_idx', [0.1, 0.2, 0.3]);
console.log(matches.results);

Last Updated: January 2026 API Version: v1 HeliosDB Version: 7.0.0

HeliosDB HTTP/REST API Reference

HeliosDB HTTP/REST API Reference

Table of Contents

Base Configuration

Base URLs

Request Headers

Authentication

Query Endpoints

Execute SQL Query

Execute Async Query

Get Async Query Status

Stream Query Results

Cancel Query

Explain Query

Table Management

List Tables

Get Table Schema

Create Table

Alter Table

Drop Table

Row Operations (CRUD)

Read Rows

Insert Rows

Update Rows

Delete Rows

Get Row by ID

Update Row by ID

Delete Row by ID

Transaction Endpoints

Begin Transaction

Execute in Transaction

Commit Transaction

Rollback Transaction

Vector Operations

Vector Search

Upsert Vectors

Delete Vectors

Admin Endpoints

Health Check

Readiness Check

Liveness Check

Server Info

Prometheus Metrics

Error Handling

Error Response Format

HTTP Status Codes

Common Error Codes

Rate Limiting

Rate Limit Headers

Rate Limit Response (429)

Pagination

Offset-Based Pagination

Cursor-Based Pagination (Recommended)

Best Practices

SDK Examples

Python

JavaScript/TypeScript