# HeroDB JSON-RPC Examples

These examples show full JSON-RPC 2.0 payloads for managing HeroDB via the RPC API (enable with `--enable-rpc`). Methods are named as `hero_<function>`. Params are positional arrays; enum values are strings (e.g., `"Redb"`). Copy-paste into Postman or similar clients.

## Database Management

### Create Database
Creates a new database with optional per-database encryption key (stored write-only in Admin DB 0).

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "hero_createDatabase",
  "params": [
    "Redb",
    { "name": null, "storage_path": null, "max_size": null, "redis_version": null },
    null
  ]
}
```

With encryption:
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "hero_createDatabase",
  "params": [
    "Sled",
    { "name": "secure-db", "storage_path": null, "max_size": null, "redis_version": null },
    "my-per-db-encryption-key"
  ]
}
```

### List Databases
Returns array of database infos (id, backend, encrypted status, size, etc.).

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "hero_listDatabases",
  "params": []
}
```

### Get Database Info
Retrieves detailed info for a specific database.

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "hero_getDatabaseInfo",
  "params": [1]
}
```

### Delete Database
Removes physical database file; metadata remains in Admin DB 0.

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "hero_deleteDatabase",
  "params": [1]
}
```

## Access Control

### Add Access Key
Adds a hashed access key for private databases. Permissions: `"read"` or `"readwrite"`.

```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "hero_addAccessKey",
  "params": [2, "my-access-key", "readwrite"]
}
```

### List Access Keys
Returns array of key hashes, permissions, and creation timestamps.

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "hero_listAccessKeys",
  "params": [2]
}
```

### Delete Access Key
Removes key by its SHA-256 hash.

```json
{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "hero_deleteAccessKey",
  "params": [2, "0123abcd...keyhash..."]
}
```

### Set Database Public/Private
Toggles public access (default true). Private databases require access keys.

```json
{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "hero_setDatabasePublic",
  "params": [2, false]
}
```

## Server Info

### Get Server Stats
Returns stats like total databases and uptime.

```json
{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "hero_getServerStats",
  "params": []
}
```

## Notes
- Per-database encryption keys are write-only; set at creation and used transparently.
- Access keys are hashed (SHA-256) for storage; provide plaintext in requests.
- Backend options: `"Redb"` (default) or `"Sled"`.
- Config object fields (name, storage_path, etc.) are optional and currently ignored but positional.