Skip to content
HeliosDB HeliosDB Full

HeliosDB API Reference Overview

HeliosDB API Reference Overview

Version: 7.0 Last Updated: January 2026

This directory contains comprehensive API reference documentation for HeliosDB, covering all interfaces and access methods available for interacting with the database.

Table of Contents

  1. API Interfaces
  2. HTTP/REST API
  3. gRPC API
  4. WebSocket API
  5. Authentication Methods
  6. Rate Limiting
  7. API Versioning
  8. Related Documentation

API Interfaces

HeliosDB provides multiple API interfaces to accommodate different use cases, integration patterns, and performance requirements:

InterfacePortProtocolUse Case
HTTP/REST8080 (HTTP), 443 (HTTPS)HTTP/1.1, HTTP/2Web applications, microservices, general integration
gRPC50051HTTP/2High-performance, low-latency, service-to-service
WebSocket8081WS/WSSReal-time subscriptions, streaming, live updates
PostgreSQL Wire5432PostgreSQL v3SQL clients, ORM frameworks, migrations
MongoDB Wire27017MongoDB WireDocument-style operations, existing MongoDB apps
Redis Protocol6379RESP3Caching, key-value operations, pub/sub
Cassandra CQL9042CQL BinaryWide-column operations, existing Cassandra apps
GraphQL8080/graphqlHTTP POSTFlexible queries, frontend applications

Choosing an API Interface

  • HTTP/REST API: Best for most applications, easy integration, language-agnostic
  • gRPC API: Best for microservices, high throughput, strongly-typed contracts
  • WebSocket API: Best for real-time updates, live dashboards, streaming data
  • Wire Protocols: Best when migrating from existing databases or using native drivers

HTTP/REST API

The primary HTTP/REST API provides full database functionality through RESTful endpoints.

Base URLs

Production:  https://api.heliosdb.io/api/v1
Development: http://localhost:8080/api/v1

Core Endpoints

CategoryEndpointDescription
QueryPOST /queryExecute SQL queries
QueryPOST /query/asyncExecute async queries
QueryPOST /query/streamStream query results
TablesGET /tablesList all tables
TablesGET /tables/{name}Get table schema
TablesPOST /tablesCreate new table
TablesDELETE /tables/{name}Drop table
CRUDGET /tables/{name}/rowsRead rows
CRUDPOST /tables/{name}/rowsInsert rows
CRUDPUT /tables/{name}/rowsUpdate rows
CRUDDELETE /tables/{name}/rowsDelete rows
VectorPOST /vectors/searchVector similarity search
VectorPOST /vectors/upsertUpsert vectors
AdminGET /healthHealth check
AdminGET /metricsPrometheus metrics
AdminGET /infoServer information

Quick Example

Terminal window
# Execute a SQL query
curl -X POST https://api.heliosdb.io/api/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM users WHERE status = $1 LIMIT 10", "params": ["active"]}'

Full documentation: HTTP_REST_API.md

gRPC API

HeliosDB provides a high-performance gRPC API for service-to-service communication with strongly-typed contracts.

Connection

Endpoint: grpc.heliosdb.io:50051
TLS: Required in production

Service Definition

syntax = "proto3";


package heliosdb.v1;


service HeliosDB {
  // Query operations
  rpc ExecuteQuery(QueryRequest) returns (QueryResponse);
  rpc ExecuteQueryStream(QueryRequest) returns (stream Row);


  // Transaction operations
  rpc BeginTransaction(BeginTransactionRequest) returns (TransactionResponse);
  rpc CommitTransaction(TransactionId) returns (CommitResponse);
  rpc RollbackTransaction(TransactionId) returns (RollbackResponse);


  // Vector operations
  rpc VectorSearch(VectorSearchRequest) returns (VectorSearchResponse);
  rpc VectorUpsert(VectorUpsertRequest) returns (VectorUpsertResponse);


  // Admin operations
  rpc HealthCheck(Empty) returns (HealthResponse);
}


message QueryRequest {
  string sql = 1;
  repeated Value params = 2;
  optional TransactionId transaction_id = 3;
}


message QueryResponse {
  repeated Column columns = 1;
  repeated Row rows = 2;
  int64 affected_rows = 3;
  QueryMetrics metrics = 4;
}


message VectorSearchRequest {
  string index_name = 1;
  repeated float vector = 2;
  int32 top_k = 3;
  optional string filter = 4;
  bool include_vectors = 5;
  bool include_metadata = 6;
}

Client Libraries

LanguagePackageInstallation
Pythonheliosdb-grpcpip install heliosdb-grpc
Gogithub.com/heliosdb/grpc-gogo get github.com/heliosdb/grpc-go
Javaio.heliosdb:grpcMaven/Gradle
Node.js@heliosdb/grpcnpm install @heliosdb/grpc
Rustheliosdb-grpccargo add heliosdb-grpc

Python Example

import grpc
from heliosdb.v1 import heliosdb_pb2, heliosdb_pb2_grpc


# Create channel with TLS
credentials = grpc.ssl_channel_credentials()
channel = grpc.secure_channel('grpc.heliosdb.io:50051', credentials)
stub = heliosdb_pb2_grpc.HeliosDBStub(channel)


# Execute query
request = heliosdb_pb2.QueryRequest(
    sql="SELECT * FROM users WHERE age > $1",
    params=[heliosdb_pb2.Value(int_value=21)]
)
response = stub.ExecuteQuery(request, metadata=[('authorization', 'Bearer YOUR_API_KEY')])


for row in response.rows:
    print(row)

Go Example

package main


import (
    "context"
    "log"


    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    pb "github.com/heliosdb/grpc-go/heliosdb/v1"
)


func main() {
    // Create connection with TLS
    creds, _ := credentials.NewClientTLSFromFile("ca.crt", "")
    conn, err := grpc.Dial("grpc.heliosdb.io:50051", grpc.WithTransportCredentials(creds))
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()


    client := pb.NewHeliosDBClient(conn)


    // Execute query
    response, err := client.ExecuteQuery(context.Background(), &pb.QueryRequest{
        Sql: "SELECT * FROM users LIMIT 10",
    })
    if err != nil {
        log.Fatal(err)
    }


    for _, row := range response.Rows {
        log.Println(row)
    }
}

WebSocket API

The WebSocket API enables real-time subscriptions and streaming data access.

Connection

Endpoint: wss://api.heliosdb.io/ws
Protocol: WebSocket (RFC 6455)
Subprotocol: heliosdb.v1

Message Format

All messages use JSON format:

{
  "type": "request|response|event",
  "id": "unique-request-id",
  "action": "action-name",
  "data": { ... }
}

Available Actions

ActionDescription
authenticateAuthenticate the connection
subscribeSubscribe to table changes
unsubscribeUnsubscribe from changes
queryExecute a one-time query
pingKeep-alive ping

Authentication

{
  "type": "request",
  "id": "auth-1",
  "action": "authenticate",
  "data": {
    "token": "YOUR_API_KEY"
  }
}

Subscribe to Changes

{
  "type": "request",
  "id": "sub-1",
  "action": "subscribe",
  "data": {
    "table": "users",
    "events": ["INSERT", "UPDATE", "DELETE"],
    "filter": "status = 'active'"
  }
}

Receive Events

{
  "type": "event",
  "subscription_id": "sub-1",
  "data": {
    "event_type": "INSERT",
    "table": "users",
    "row": {
      "id": 123,
      "name": "Alice",
      "email": "alice@example.com"
    },
    "timestamp": "2026-01-04T12:00:00Z"
  }
}

JavaScript Client Example

const ws = new WebSocket('wss://api.heliosdb.io/ws', 'heliosdb.v1');


ws.onopen = () => {
  // Authenticate
  ws.send(JSON.stringify({
    type: 'request',
    id: 'auth-1',
    action: 'authenticate',
    data: { token: 'YOUR_API_KEY' }
  }));
};


ws.onmessage = (event) => {
  const message = JSON.parse(event.data);


  if (message.type === 'response' && message.id === 'auth-1') {
    // Authentication successful, subscribe to changes
    ws.send(JSON.stringify({
      type: 'request',
      id: 'sub-1',
      action: 'subscribe',
      data: {
        table: 'orders',
        events: ['INSERT']
      }
    }));
  }


  if (message.type === 'event') {
    console.log('New order:', message.data.row);
  }
};


// Keep connection alive
setInterval(() => {
  ws.send(JSON.stringify({ type: 'request', action: 'ping' }));
}, 30000);

Python Client Example

import asyncio
import websockets
import json


async def subscribe_to_orders():
    async with websockets.connect(
        'wss://api.heliosdb.io/ws',
        subprotocols=['heliosdb.v1']
    ) as ws:
        # Authenticate
        await ws.send(json.dumps({
            'type': 'request',
            'id': 'auth-1',
            'action': 'authenticate',
            'data': {'token': 'YOUR_API_KEY'}
        }))


        auth_response = json.loads(await ws.recv())
        if auth_response.get('success'):
            # Subscribe to orders table
            await ws.send(json.dumps({
                'type': 'request',
                'id': 'sub-1',
                'action': 'subscribe',
                'data': {
                    'table': 'orders',
                    'events': ['INSERT', 'UPDATE']
                }
            }))


            # Listen for events
            async for message in ws:
                data = json.loads(message)
                if data['type'] == 'event':
                    print(f"Order event: {data['data']}")


asyncio.run(subscribe_to_orders())

Authentication Methods

HeliosDB supports multiple authentication methods to accommodate different security requirements.

API Key Authentication

The simplest authentication method, suitable for server-to-server communication.

Request Header:

Authorization: Bearer hdb_sk_abc123xyz...

Alternative Header:

X-API-Key: hdb_sk_abc123xyz...

Key Format:

  • Production keys: hdb_sk_ prefix (secret key)
  • Public keys: hdb_pk_ prefix (limited access)
  • Test keys: hdb_test_ prefix (test environment only)

JWT Token Authentication

For user-based authentication with fine-grained permissions and expiration.

Token Generation:

Terminal window
# Login to obtain token
curl -X POST https://api.heliosdb.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "user@example.com", "password": "password"}'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using JWT Token:

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Token Refresh:

Terminal window
curl -X POST https://api.heliosdb.io/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJSUzI1NiIs..."}'

OAuth 2.0 / OIDC

For enterprise SSO integration with identity providers.

Supported Providers:

  • Google Workspace
  • Microsoft Azure AD
  • Okta
  • Auth0
  • Custom OIDC providers

Configuration:

authentication:
  oauth2:
    enabled: true
    provider: azure
    client_id: "YOUR_CLIENT_ID"
    client_secret: "YOUR_CLIENT_SECRET"
    tenant_id: "YOUR_TENANT_ID"
    scopes:
      - openid
      - profile
      - email

mTLS (Mutual TLS)

For the highest security requirements with certificate-based authentication.

Client Certificate:

Terminal window
curl --cert client.crt --key client.key \
  https://api.heliosdb.io/api/v1/tables

Configuration:

tls:
  enabled: true
  cert_file: /certs/server.crt
  key_file: /certs/server.key
  client_auth: require
  client_ca_file: /certs/ca.crt

Database Authentication (Wire Protocols)

For PostgreSQL, MySQL, and other wire protocol connections.

PostgreSQL (MD5/SCRAM-SHA-256):

postgresql://username:password@localhost:5432/heliosdb

Supported Methods:

  • Password (MD5 hash)
  • SCRAM-SHA-256 (recommended)
  • Certificate-based
  • LDAP/Active Directory
  • GSSAPI/Kerberos

Rate Limiting

HeliosDB implements rate limiting to ensure fair usage and system stability.

Rate Limit Tiers

TierRequests/SecondRequests/HourConcurrent
Free101,0005
Developer10010,00025
Professional1,000100,000100
EnterpriseCustomCustomCustom

Rate Limit Headers

Every API response includes rate limit headers:

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

Handling Rate Limits

When rate limited, the API returns HTTP 429:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retry_after": 60
  }
}

Best Practices:

  1. Implement exponential backoff
  2. Use the Retry-After header
  3. Batch operations where possible
  4. Cache frequently accessed data
  5. Use streaming for large result sets

Example with Retry Logic

import requests
import time


def api_call_with_retry(url, data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, json=data, headers=headers)


        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f"Rate limited. Retrying in {retry_after} seconds...")
            time.sleep(retry_after)
            continue


        return response


    raise Exception("Max retries exceeded")

API Versioning

Current Version

The current stable API version is v1.

Version Format

API versions are included in the URL path:

/api/v1/...  # Current stable
/api/v2/...  # Future (when available)

Version Lifecycle

PhaseDurationDescription
Preview3 monthsNew features, may change
Stable24+ monthsProduction-ready, backward compatible
Deprecated12 monthsStill works, migration warnings
Sunset-No longer available

Deprecation Notices

Deprecated features are indicated via response headers:

Deprecation: true
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
Link: </api/v2/query>; rel="successor-version"

Migration Support

Terminal window
# Check API version compatibility
curl https://api.heliosdb.io/api/v1/info \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "version": "7.0.0",
  "api_version": "v1",
  "supported_versions": ["v1"],
  "deprecated_features": [
    {
      "feature": "/api/v1/legacy/query",
      "sunset_date": "2027-01-01",
      "replacement": "/api/v1/query"
    }
  ]
}

API Reference Files

DocumentDescription
HTTP_REST_API.mdComplete HTTP REST API reference
SQL_FUNCTIONS.mdSQL function reference
DDL_REFERENCE.mdDDL statement reference

External Documentation

DocumentLocation
Main API Reference/docs/api/API_REFERENCE.md
SQL API Reference/docs/api/SQL_API_REFERENCE.md
OpenAPI Specification/docs/reference/OPENAPI_SPECIFICATION.md
Protocol Documentation/docs/reference/protocols/

Protocol-Specific Documentation

ProtocolDocumentation
PostgreSQL/docs/reference/protocols/postgresql/
MongoDB/docs/reference/protocols/mongodb/
Redis/docs/reference/protocols/redis/
Cassandra/docs/reference/protocols/cassandra/
GraphQL/docs/reference/protocols/graphql/
HTTP/REST/docs/reference/protocols/http-rest/

Support

For API support and questions:

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