# HeliosDB BaaS — AI Agent Integration Guide

## Overview

HeliosDB Cloud provides a Backend-as-a-Service on managed HeliosDB Nano with instant database provisioning, branching, time-travel queries, vector search, and per-database API keys. The free tier needs no credit card and has quotas (see Free Tier Quotas); some tools need a Starter or Pro plan, as marked in the MCP tool table. HeliosDB Cloud is in an Experimental Period: every plan is free of charge for every customer, limits are indicative, and there is no trial of any kind (see Terms and commitments).

File storage (buckets and signed URLs) and edge functions are not part of HeliosDB Cloud. They are on the HeliosDB roadmap; today self-hosted Nano serves PostgREST-style REST, auth and a realtime WebSocket, and stores data in its data directory (known issues in the current release: the /rest/v1 table routes, and realtime events, which are not delivered; tracked by the Nano team).

- **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:** per-database API key (`X-API-Key: hdb_...` or `Authorization: Bearer hdb_...`) or a session JWT (`Authorization: Bearer <token>`). Required on every endpoint except quick-start, signup and login — including MCP.

## 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",
  "accept_terms": true
}
```

The Instant level is exempt from the business email rule: the email may be any address you receive mail at, and with a personal mailbox address (such as gmail.com or outlook.com) the account is API-only: no console sign-in and no email verification, and it stays at the Instant level (the response says `"api_only": true`). The Verified level and above, console sign-in and paid plans need a business email address (`422 BUSINESS_EMAIL_REQUIRED` or `403 API_ONLY_ACCOUNT` otherwise). `"accept_terms": true` accepts the Cloud Terms of Service, the Data Processing Agreement and the Transaction Durability Commitment for your organization (without it: `422 TERMS_NOT_ACCEPTED`); `GET https://cloud.heliosdb.com/api/v1/legal/terms` lists the current versions, and you may send its `terms_version` with the request.

**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"}
```

Time-travel retention: Free 7 days (14 days after a feedback session), Starter 30 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)

`https://cloud.heliosdb.com/api/v1/mcp` is a remote MCP server (Streamable HTTP, JSON responses). Standard MCP clients connect to it directly — Claude Code, Cursor, VS Code, the MCP Inspector, and the official TypeScript and Python SDKs. Every request needs a credential, sent as a static header:

- `Authorization: Bearer hdb_...` or `X-API-Key: hdb_...` — the per-database API key. `quick-start` returns one as `api_key`; create more with `POST .../databases/{db_id}/api-keys` or in the console (Databases → API Keys → Generate key).
- `Authorization: Bearer <token>` — the session JWT from `quick-start` or `POST /api/v1/auth/login`.

There is no OAuth flow; configure the key as a header. Without a valid credential the endpoint answers `401` (`WWW-Authenticate: Bearer`).

### Connect a client

Claude Code:
```bash
claude mcp add --transport http heliosdb https://cloud.heliosdb.com/api/v1/mcp \
  --header "Authorization: Bearer $HDB_API_KEY"
```

Cursor / VS Code (`mcp.json`):
```json
{
  "mcpServers": {
    "heliosdb": {
      "url": "https://cloud.heliosdb.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer hdb_..." }
    }
  }
}
```

MCP Inspector (CLI):
```bash
npx @modelcontextprotocol/inspector@latest --cli https://cloud.heliosdb.com/api/v1/mcp \
  --transport http --header "Authorization: Bearer $HDB_API_KEY" --method tools/list
```

### Protocol

- Protocol versions `2026-07-28` (stateless: `server/discover`, `tools/list`, `tools/call`) and `2025-11-25`, `2025-06-18`, `2025-03-26` (`initialize`, `notifications/initialized`, `ping`, `tools/list`, `tools/call`). Clients negotiate the version themselves.
- Stateless: no `Mcp-Session-Id` is issued, `GET` and `DELETE` answer `405` (no standalone SSE stream), responses are `application/json`. Any request can go to any server.
- JSON-RPC batches only at `2025-03-26`.
- A tool call runs the same checks as the REST endpoint behind it: the token's organization must match `org_id`, an API key works only for its own database, and `read`/`write` scopes, tier gates and quotas apply. A refused or failed call comes back as a normal result with `isError: true` and the reason (for example `FORBIDDEN: this API key is bound to a different database`), so the agent can read it. An unknown tool is JSON-RPC error `-32602`.
- Each `tools/call` counts once against the organization's monthly API request allowance (`initialize`, `tools/list` and `ping` do not). Over the limit: `429` with `Retry-After`.

Plain JSON-RPC also works without an MCP client:
```bash
curl -X POST https://cloud.heliosdb.com/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HDB_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
```

Call a tool:
```bash
curl -X POST https://cloud.heliosdb.com/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HDB_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "execute_sql",
      "arguments": {
        "org_id": "...",
        "db_id": "...",
        "sql": "SELECT * FROM users WHERE id = $1",
        "params": [42]
      }
    },
    "id": 2
  }'
```

### Available MCP Tools

All 27 tools work over MCP. `tools/list` returns each one with its JSON input schema and read-only/destructive hints.

| Tool | Description |
|------|-------------|
| `list_databases`, `create_database`, `delete_database` | List, create and delete an organization's databases (create/delete need a `write` or `admin` key or an owner/admin session) |
| `execute_sql` | Run SQL on a database (`$1, $2, ...` with `params`) |
| `query_at` | Time-travel query |
| `list_branches`, `create_branch`, `switch_branch`, `merge_branch`, `delete_branch` | Branching (create: Pro+) |
| `create_api_key` | Create a scoped API key for a database |
| `vector_search` | Vector similarity search (HNSW, Pro+) |
| `analytics_overview`, `analytics_query_stats` | Table/database stats and slow-query top-N (Pro+) |
| `list_materialized_views`, `refresh_materialized_view` | Materialized views (Pro+) |
| `list_experiments`, `delete_experiment`, `assign_variant` | Branch-based A/B experiments |
| `replication_status`, `list_replication_slots`, `create_replication_slot`, `drop_replication_slot` | Replication (Enterprise tier; no Enterprise plan is offered during the Experimental Period) |
| `ddl_history` | Recent DDL operations (Enterprise tier, as above) |
| `verify_email` | Verify the organization's email with the token from the verification email |
| `logout` | End the console session the request is authenticated with (session JWT only; revoke API keys instead) |
| `mark_trusted` | Mark an organization trusted (platform operators only) |

Account creation stays REST-only (`POST /api/v1/quick-start`); it is not an MCP tool.

The AI-native retrieval tools (`helios_graphrag_search`, `heliosdb_hybrid_search`, LSP tools, …) and the `helios/info`, `/mcp/info`, WebSocket and SSE transports belong to a self-hosted HeliosDB Nano MCP server (`POST /mcp` on your own instance) — see https://www.heliosdb.com/nano.html. They are not part of the Cloud endpoint.

## Free Tier Quotas

The Free plan includes 1 database, 100 MB of storage, 5 connections, 10K vectors, 10K API requests a month and 7 days of time-travel retention, with AES-256-GCM encryption at rest and zero-knowledge encryption. It grows in three levels (all free, no credit card); the numbers match https://www.heliosdb.com/pricing.html.

These levels apply to accounts created through the API (`POST /api/v1/quick-start` or `POST /api/v1/auth/signup-baas`), which start at the Instant level. Instant is the standard free level of the agent-ready BaaS: an API signup creates the account, database and key with no human step. The signup may use any email address; with a personal mailbox address (such as gmail.com or outlook.com) the account is API-only: no console sign-in and no email verification, and it stays at the Instant level. Console accounts at https://cloud.heliosdb.com are for people with a business email address (personal mailbox domains such as gmail.com, yahoo.com and outlook.com are not accepted) and start at the Verified level after email verification; see https://www.heliosdb.com/cloud.html.

| Resource | Instant (signup) | Verified (email) | Feedback given |
|----------|------------------|------------------|----------------|
| Storage | 100 MB | 500 MB | 1 GB |
| Databases | 1 | 3 | 4 |
| Connections | 5 | 5 | 10 |
| Vectors | 10K | 50K | 100K |
| API requests/month | 10K | 50K | 100K |
| Time-travel retention | 7 days | 7 days | 14 days |

Upgrade path: signup → verify email → opt in for feedback and complete a session with the team. Starter gives 5 databases, 1 GB, 20 connections, 100K vectors and 100K API requests a month; Pro gives 20 databases, 10 GB, 100 connections, 1M vectors and 1M requests. During the Experimental Period both cost $0/mo for every customer and their limits are indicative; reference prices for after it, which apply only under new terms the customer accepts expressly, are $9/mo for Starter and $49/mo for Pro. No Enterprise plan and no add-on is offered during the period. Every plan encrypts data at rest with AES-256-GCM; Starter and up include all encryption modes.

## Terms and commitments

- Accounts are for organisations. Console accounts, and every account at the Verified level or above, need a business email address; personal mailbox domains are accepted only for API-only accounts at the Instant level. There is no trial of any kind, and no plan turns into a paid plan.
- No availability or uptime commitment and no service credits. The Transaction Durability Commitment applies instead: a transaction the service has acknowledged as committed is not lost because of the version of the HeliosDB engine HeliosDB runs, including upgrades. HeliosDB Cloud does not route connections through HeliosProxy today; if it does, the commitment covers that too. It does not cover deletes made with the customer's credentials, or hardware or site failures that destroy the data and all its copies; a restore from the daily backup can lose up to about 24 hours of changes. One known limitation of the engine is excluded where its workaround is not used: statements outside an explicit transaction that read and change the same row from several sessions at once can lose updates, so run them in an explicit transaction and retry on a serialization failure. https://www.heliosdb.com/transaction-durability.html
- Support is best effort and AI-coordinated, from the available pool of HeliosDB workers, with non-binding targets and no service credits: https://www.heliosdb.com/support-policy.html
- Cloud Terms of Service and Acceptable Use Policy: https://www.heliosdb.com/cloud-terms.html. Data Processing Agreement: https://www.heliosdb.com/dpa.html. Privacy Notice: https://www.heliosdb.com/privacy.html

## 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
- Plain-SQL DO blocks and simple SQL/plpgsql functions (PL/pgSQL control flow and trigger bodies are planned)
- Full-text search with BM25 scoring