# HeliosDB BaaS — AI Agent Integration Guide

## Overview

HeliosDB Cloud provides a Backend-as-a-Service with instant database provisioning, branching, time-travel queries, vector search, and per-database API keys. All features are available on the free tier (with quotas).

- **Base URL:** `https://cloud.heliosdb.com`
- **OpenAPI 3.1 Spec:** `https://cloud.heliosdb.com/api/v1/openapi.json`
- **MCP Endpoint:** `POST https://cloud.heliosdb.com/api/v1/mcp`
- **Auth:** Bearer JWT token or `X-API-Key: hdb_...` header

## Quick Start (Single Request)

```bash
POST /api/v1/quick-start
Content-Type: application/json

{
  "email": "agent@myapp.com",
  "password": "securepassword",
  "username": "agent",
  "org_name": "MyApp",
  "db_name": "main"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "token": "eyJ...",
    "org_id": "uuid",
    "db_id": "uuid",
    "api_key": "hdb_...",
    "endpoints": {
      "execute": "/api/v1/organizations/{org_id}/databases/{db_id}/execute",
      "branches": "/api/v1/organizations/{org_id}/databases/{db_id}/branches",
      "query_at": "/api/v1/organizations/{org_id}/databases/{db_id}/query-at",
      "api_keys": "/api/v1/organizations/{org_id}/databases/{db_id}/api-keys"
    }
  }
}
```

## Execute SQL

```bash
POST /api/v1/organizations/{org_id}/databases/{db_id}/execute
X-API-Key: hdb_...
Content-Type: application/json

{"sql": "CREATE TABLE users (id SERIAL, name TEXT, embedding VECTOR(768))"}
```

## Branching

### List Branches
```
GET .../databases/{db_id}/branches
```

### Create Branch
```bash
POST .../databases/{db_id}/branches
{"name": "feature-1", "as_of": "now"}
```
Supported `as_of` values: `now`, `timestamp:<ISO8601>`, `transaction:<id>`, `scn:<id>`. Optional `from` field specifies parent branch.

### Switch Branch
```bash
POST .../databases/{db_id}/branches/switch
{"name": "feature-1"}
```

### Merge Branch
```bash
POST .../databases/{db_id}/branches/merge
{"source": "feature-1", "target": "main"}
```

### Delete Branch
```
DELETE .../databases/{db_id}/branches/{name}
```

## Time-Travel Queries

```bash
POST .../databases/{db_id}/query-at
{"sql": "SELECT * FROM users", "as_of": "2025-06-01T00:00:00Z"}
```

Free tier: 24-hour lookback. Starter: 7 days. Pro: 90 days.

## API Keys (Per-Database)

### Create
```bash
POST .../databases/{db_id}/api-keys
{"name": "frontend", "scopes": ["read", "write"]}
```
Returns raw key once (prefix `hdb_`). Store it securely.

### List
```
GET .../databases/{db_id}/api-keys
```

### Revoke
```
DELETE .../databases/{db_id}/api-keys/{key_id}
```

## MCP (Model Context Protocol)

Discover all tools:
```bash
POST /api/v1/mcp
Content-Type: application/json

{"jsonrpc": "2.0", "method": "tools/list", "id": 1}
```

Call a tool:
```bash
POST /api/v1/mcp
Authorization: Bearer {token}
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "execute_sql",
    "arguments": {
      "org_id": "...",
      "db_id": "...",
      "sql": "SELECT * FROM users"
    }
  },
  "id": 2
}
```

### Available MCP Tools

| Tool | Description |
|------|-------------|
| `quick_start` | Create account, database, and API key |
| `execute_sql` | Run SQL on a database |
| `create_database` | Create a new database |
| `list_databases` | List databases in an org |
| `create_branch` | Create a branch (with as_of, from) |
| `switch_branch` | Switch active branch |
| `merge_branch` | Merge branches |
| `list_branches` | List all branches |
| `query_at` | Time-travel query |
| `create_api_key` | Create scoped API key |

### v3.19 AI-Native Retrieval Tools

The same MCP endpoint surfaces every Nano v3.19 tool automatically — no separate registration:

| Tool | Description |
|------|-------------|
| `helios_graphrag_search` | Cross-modal `WITH CONTEXT` query as a tool (streaming progress) |
| `helios_lsp_document_symbols` | File outline, ordered by line, optional kind filter |
| `helios_lsp_rename_preview` | Preview a rename refactor with sha256 conflict check |
| `helios_lsp_rename_apply` | Write-back rename refactor (identifier-boundary aware) |
| `helios_lsp_references_diff` | Diff references between two AS OF refs |
| `helios_lsp_body_diff` | Diff symbol bodies between two refs |
| `helios_ast_diff` | AST diff between two refs |
| `heliosdb_bm25_index` | Build a BM25 index on a column |
| `heliosdb_hybrid_search` | RRF / MMR fusion over BM25 + vector |
| `heliosdb_graph_add_edge` | Insert a graph edge |
| `heliosdb_graph_traverse` | BFS / DFS traversal |
| `heliosdb_embed_and_store` | Embed a string and persist the vector |

Single-shot discovery:

```bash
GET https://cloud.heliosdb.com/api/v1/mcp/info
```

Or as JSON-RPC:

```bash
POST /api/v1/mcp
{"jsonrpc":"2.0","method":"helios/info","id":1}
```

Streaming progress events via WebSocket:

```
ws://cloud.heliosdb.com/api/v1/mcp/ws
```

Pair `Mcp-Session-Id` header on `POST /api/v1/mcp` with an open SSE channel at `/api/v1/mcp/sse` to forward `notifications/progress` events while the POST returns the final response.

## Free Tier Quotas

### Sub-Levels (all free, no credit card)

| Resource | Unverified | Verified (email) | Trusted (feedback) |
|----------|-----------|-------------------|-------------------|
| Databases | 3 | 5 | 7 |
| Storage | 5 MB | 50 MB | 200 MB |
| Queries/hour | 200 | 500 | 2,000 |
| Branches | 3 | 10 | 20 |
| Time-travel | 24h | 3 days | 7 days |
| Tables/DB | 10 | 50 | 200 |

Upgrade path: signup → verify email → opt in for feedback + complete session with team.
| Vector search | Included |
| Graph traversal | Included |
| BM25 hybrid search | Included |

## SQL Features

HeliosDB is PostgreSQL wire-compatible and supports:
- Standard SQL (DDL, DML, queries, joins, aggregations)
- `VECTOR(n)` column type with HNSW indexing
- `CREATE BRANCH`, `USE BRANCH`, `MERGE BRANCH`, `DROP BRANCH`
- `SELECT ... AS OF TIMESTAMP '...'` for time-travel
- Materialized views with incremental refresh
- Stored procedures and triggers
- Full-text search with BM25 scoring