---
title: "HeliosDB Full API Reference"
---

# HeliosDB Full API Reference

Reference for the WASM procedure SDK, the planned webhook and scheduler HTTP API,
Prometheus metric names and the server configuration schema of HeliosDB Full.

---

## WASM procedure SDKs

:::caution[WASM procedures are not yet available in the server]
The current `heliosdb-full` server does not run WASM procedures. SQL that
would create or call one fails with SQLSTATE `0A000`. The Go SDK below builds
modules for the WASM host in the HeliosDB Full source, so they will load once
the server enables that host.
:::

| Language | Published SDK |
|----------|---------------|
| Go (TinyGo) | `github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go/wasm` (below) |
| Python, JavaScript, Rust | None. The `heliosdb` Python module, the `heliosdb` JavaScript module and the `heliosdb-wasm-sdk` crate described in earlier versions of this page are not published. |

For application access to HeliosDB Full from these languages, use a
PostgreSQL driver: see [SDKs](https://www.heliosdb.com/docs/full/api/sdks/).

## Go SDK API

### Package: `github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go/wasm/heliosdb`

Install with `go get github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go/wasm@latest`
and build procedures with
`tinygo build -target=wasm-unknown -gc=conservative -opt=z -no-debug -o procedure.wasm .`.
Procedures are exported with `//export` and take and return WASM scalars.
The module imports only the host's `env` functions (no WASI). Source and
examples: [sdks/go/wasm](https://github.com/HeliosDatabase/HeliosDB-SDKs/tree/main/sdks/go/wasm).

#### SQL

| Function | Description |
|----------|-------------|
| `Exec(sql string) (int64, error)` | Run a statement and return the rows affected (`heliosdb_execute`) |
| `Quote(s)`, `QuoteIdent(s)`, `Int64(v)` | Build SQL literals (the ABI has no bind parameters) |

Procedures cannot read query results. The host functions that return rows
write them to a host-chosen address in the module's memory, so the SDK does
not expose them (see [Host Functions](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_host_functions/)).

**Example:**
```go
import "github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go/wasm/heliosdb"

//export deactivate_user
func deactivateUser(id int64) int32 {
    if _, err := heliosdb.Exec("UPDATE users SET active = false WHERE id = " + heliosdb.Int64(id)); err != nil {
        heliosdb.LogError(err.Error())
        return -1
    }
    return 0
}
```

#### Transactions

| Function | Description |
|----------|-------------|
| `Begin() (Tx, error)` | Start a transaction |
| `Tx.Commit() error`, `Tx.Rollback() error` | Finish it |
| `WithTx(fn func(Tx) error) error` | Commit on success, roll back on error |

#### Key-value store and logging

| Function | Description |
|----------|-------------|
| `StorageWrite(key string, value []byte) error` | Write to the host key-value store |
| `Log(level, msg)`, `LogTrace` … `LogError` | Write to the server log |

Failed host calls return `*heliosdb.HostError` with the host's return code.

#### Testing

`github.com/HeliosDatabase/HeliosDB-SDKs/sdks/go/wasm/heliosdbtest` provides an
in-memory host: `fake := heliosdbtest.Install(t)` records SQL, transactions,
logs and key-value writes so procedures can be tested with `go test`.

---

## HTTP API

:::caution[Planned]
Webhooks, the cron scheduler and edge functions for HeliosDB Full are planned and
are not in the current release. The `/api/webhooks` and `/api/jobs` routes below
describe the planned API; the HTTP gateway (port 8443) does not serve
them yet. What the server answers over HTTP today is `/health`, `/ready`, `/status`,
`POST /api/v1/query` and the AI routes: see the
[HTTP REST API reference](/docs/full/reference/api/http_rest_api/).
:::

### Webhook Management (planned)

#### `POST /api/webhooks`
Register new webhook.

**Request:**
```json
{
  "endpoint": "/github/push",
  "provider": "github",
  "secret": "webhook-secret",
  "function": "handle_github_push",
  "ip_whitelist": ["192.30.252.0/22"]
}
```

**Response:**
```json
{
  "id": "wh_123abc",
  "endpoint": "/github/push",
  "created_at": "2025-10-30T12:00:00Z"
}
```

#### `GET /api/webhooks`
List all webhooks.

**Response:**
```json
{
  "webhooks": [
    {
      "id": "wh_123abc",
      "endpoint": "/github/push",
      "provider": "github",
      "enabled": true
    }
  ]
}
```

#### `DELETE /api/webhooks/:id`
Delete webhook.

**Response:** `204 No Content`

### Scheduler API (planned)

#### `POST /api/jobs`
Create cron job.

**Request:**
```json
{
  "name": "daily_cleanup",
  "cron": "0 2 * * *",
  "timezone": "America/New_York",
  "function": "daily_cleanup",
  "enabled": true
}
```

**Response:**
```json
{
  "id": "job_456def",
  "name": "daily_cleanup",
  "next_run": "2025-10-31T02:00:00-04:00"
}
```

#### `GET /api/jobs`
List all jobs.

**Response:**
```json
{
  "jobs": [
    {
      "id": "job_456def",
      "name": "daily_cleanup",
      "cron": "0 2 * * *",
      "enabled": true,
      "last_run": "2025-10-30T02:00:00-04:00",
      "next_run": "2025-10-31T02:00:00-04:00"
    }
  ]
}
```

---

## Prometheus Metrics

### WASM Metrics

```
heliosdb_wasm_invocations_total{module, function, status}
heliosdb_wasm_execution_duration_seconds{module, function}
heliosdb_wasm_cache_hits_total{tier}
heliosdb_wasm_pool_utilization{module}
heliosdb_wasm_memory_bytes{module}
```

### Edge Function Metrics

:::caution[Planned]
Serverless edge functions for HeliosDB Full are on the roadmap and are not
available in the current release; the edge, webhook and cron metrics below arrive with
them.
:::

```
heliosdb_edge_events_total{source, status}
heliosdb_cdc_events_total{table, operation}
heliosdb_webhook_requests_total{provider, status}
heliosdb_cron_executions_total{job, status}
```

### Database Metrics

```
heliosdb_queries_total{status}
heliosdb_query_duration_seconds
heliosdb_connections_active
heliosdb_transactions_total{status}
```

---

## Configuration Reference

### Complete Config Schema

```toml
[server]
host = "0.0.0.0"
port = 5432
max_connections = 100

[wasm.cache]
aot_enabled = true
aot_cache_dir = "/var/lib/heliosdb/wasm_cache"
aot_max_size_gb = 5
aot_max_age_days = 7

[wasm.pool]
instance_pool_min_per_module = 5
instance_pool_max_per_module = 20
instance_pool_idle_timeout_secs = 300

[wasm.execution]
default_timeout_ms = 5000
default_memory_limit_mb = 16
enable_fuel_metering = true

# Planned: [edge_functions] is not read by the current release
[edge_functions]
enabled = true
cdc_enabled = true
webhook_server_enabled = true
scheduler_enabled = true

[monitoring]
prometheus_enabled = true
prometheus_port = 9090
opentelemetry_enabled = true
```

The `[edge_functions]` section (edge functions, CDC triggers, the webhook server
and the scheduler) is planned together with those features.