Skip to content

HTTP/REST API Protocol

HeliosDB provides a comprehensive HTTP/REST API for programmatic access, enabling integration with any language or platform that supports HTTP.

Overview

Property Value
Protocol HTTP/1.1, HTTP/2
Port 443 (HTTPS), 8080 (HTTP)
Status Production
Compatibility 75%+
Auth Methods API Key, JWT, OAuth 2.0

Quick Start

cURL

# Query with SQL
curl -X POST https://localhost:443/api/v1/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM users LIMIT 10"}'

# Insert data
curl -X POST https://localhost:443/api/v1/tables/users/rows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

Python (requests)

import requests

base_url = "https://localhost:443/api/v1"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Execute SQL query
response = requests.post(
    f"{base_url}/query",
    headers=headers,
    json={"sql": "SELECT * FROM users WHERE status = 'active'"}
)
result = response.json()
print(result["data"])

JavaScript (fetch)

const baseUrl = 'https://localhost:443/api/v1';
const headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
};

// Execute SQL query
const response = await fetch(`${baseUrl}/query`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ sql: 'SELECT * FROM users' })
});
const result = await response.json();
console.log(result.data);

Key Features

  • RESTful API design following OpenAPI 3.0 specification
  • HTTP/2 support for multiplexed connections
  • JSON and MessagePack response formats
  • Streaming responses for large result sets
  • Rate limiting and throttling
  • Comprehensive error handling with detailed messages

API Endpoints

Endpoint Method Description
/api/v1/query POST Execute SQL query
/api/v1/tables GET List all tables
/api/v1/tables/{name} GET Get table schema
/api/v1/tables/{name}/rows GET, POST, PUT, DELETE CRUD operations
/api/v1/health GET Health check
/api/v1/metrics GET Prometheus metrics

Documentation

Last Updated: January 2026