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.

Table of Contents¶

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):

href="#__codelineno-18-1">{ "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