Quick Navigation
API Reference
Complete reference for the SoliDB HTTP API. All endpoints are prefixed with /_api unless otherwise noted.
Databases
POST
/_api/database
Create a new database.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| name | string | The name of the database. | Yes |
{"name": "my_db"}
Response
200 OK
application/json
{
"name": "my_db",
"status": "created"
}
GET
/_api/databases
List all existing databases.
Response
200 OK
application/json
{
"databases": ["_system", "my_db"]
}
DELETE
/_api/database/:name
Drop a database and all its collections.
Response
204 No Content
Collections
POST
/_api/database/:db/collection
Create a new collection.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| name | string | The name of the collection. | Yes |
| type | string | Collection type: document (default), edge, or blob. |
No |
| numShards | integer | Number of shards. Default: 1. | No |
| shardKey | string | Field to shard by. Default: _key. |
No |
| replicationFactor | integer | Number of replicas. Default: 1. | No |
{"name": "users", "type": "document", "numShards": 3}
Response
200 OK
application/json
{
"name": "users",
"status": "created",
"numShards": 3,
"shardKey": "_key",
"replicationFactor": 1
}
GET
/_api/database/:db/collection
List all collections in a database.
Response
200 OK
application/json
{
"collections": [
{
"name": "users",
"count": 0,
"type": "document",
"shardConfig": { "num_shards": 3, ... },
"stats": { ... }
}
]
}
GET
/_api/database/:db/collection/:name/stats
Get collection statistics (count, size).
Response
200 OK
application/json
{
"database": "my_db",
"collection": "users",
"document_count": 1250,
"disk_usage": {
"total_size": 40960,
...
}
}
PUT
/_api/database/:db/collection/:name/properties
Update collection properties (e.g. sharding).
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| numShards | integer | New number of shards (triggers rebalance). | No |
| replicationFactor | integer | New replication factor. | No |
PUT
/_api/database/:db/collection/:name/truncate
Remove all documents from a collection.
Response
200 OK
application/json
{
"database": "my_db",
"collection": "users",
"deleted": 1250,
"status": "truncated"
}
PUT
/_api/database/:db/collection/:name/compact
Trigger compaction for a collection to reclaim space.
Response
200 OK
application/json
{
"database": "my_db",
"collection": "users",
"status": "compacted"
}
DELETE
/_api/database/:db/collection/:name
Drop a collection.
Response
204 No Content
GET
/_api/database/:db/collection/:name/export
Export collection data.
Response
200 OK
application/x-ndjson
// Stream of JSON objects (new-line delimited)
{"_key": "123", "name": "Alice"}
{"_key": "456", "name": "Bob"}
...
POST
/_api/database/:db/collection/:name/import
Import data into collection.
Supported Formats
Send raw data in the request body. Format is auto-detected:
- JSON Array:
[{"name": "a"}, {"name": "b"}] - JSONL: Newline-delimited JSON objects.
- CSV: Comma-separated values (first row as headers).
Documents
POST
/_api/database/:db/document/:collection
Create a new document.
Request Body Options
Send a JSON object representing the document. The _key field is optional; if omitted, one will be auto-generated.
{"name": "Alice", "age": 30}
Response
200 OK
application/json
{
"_key": "123456",
"_rev": "1",
"name": "Alice",
"age": 30
}
GET
/_api/database/:db/document/:collection/:key
Retrieve a document by key.
Response
200 OK
application/json
{
"_key": "123456",
"_rev": "1",
"name": "Alice",
"age": 30
}
PUT
/_api/database/:db/document/:collection/:key
Replace/Update a document.
Response
200 OK
application/json
{
"_key": "123456",
"_rev": "2",
"name": "Alice",
"age": 31
}
DELETE
/_api/database/:db/document/:collection/:key
Remove a document.
Response
204 No Content
SDBQL Queries
POST
/_api/database/:db/cursor
Execute an SDBQL query.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| query | string | The SDBQL query string. | Yes |
| bindVars | object | Key-value pairs for bind parameters. | No |
| batchSize | integer | Max documents per batch. Default: 100. | No |
{"query": "FOR d IN users RETURN d", "batchSize": 50}
Response
200 OK
application/json
{
"result": [{"_key": "...", "...": "..."}, "..."],
"count": 50,
"hasMore": true,
"id": "cursor_123",
"executionTimeMs": 1.5
}
POST
/_api/database/:db/explain
Explain query execution plan.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| query | string | The SDBQL query to explain. | Yes |
| bindVars | object | Key-value pairs for bind parameters. | No |
PUT
/_api/cursor/:id
Fetch next batch of results for a cursor.
Response
200 OK
application/json
{
"result": ["...", "..."],
"count": 50,
"hasMore": false,
"id": null,
"cached": true
}
DELETE
/_api/cursor/:id
Close a cursor and free resources.
Response
204 No Content
Indexes
POST
/_api/database/:db/index/:collection
Create a new index for a collection.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| name | string | The name of the index. | Yes |
| field | string | The document field to index (e.g., "email"). | Yes |
| type | string |
Index type. Options: persistent (default), hash, fulltext.
|
No |
| unique | boolean | If true, enforces uniqueness on the indexed field. Default: false. |
No |
{"type": "persistent", "fields": ["email"], "unique": true}
Response
200 OK
application/json
{
"name": "idx_email",
"field": "email",
"type": "persistent",
"unique": true,
"status": "created"
}
GET
/_api/database/:db/index/:collection
List all indexes for a collection.
Response
200 OK
application/json
{
"indexes": [
{ "name": "primary", "type": "primary", "fields": ["_key"], "...": "..." },
{ "name": "idx_email", "type": "persistent", "...": "..." }
]
}
PUT
/_api/database/:db/index/:collection/rebuild
Rebuild all indexes for a collection.
Response
200 OK
application/json
{
"database": "my_db",
"collection": "users",
"documents_indexed": 1250,
"status": "rebuilt"
}
DELETE
/_api/database/:db/index/:collection/:name
Drop an index.
Response
204 No Content
POST
/_api/database/:db/geo/:collection
Create a geo-spatial index.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| name | string | Index name. | Yes |
| field | string | Field to index (must contain [lat, lon] array or object). | Yes |
Response
200 OK
application/json
{
"name": "geo_location_idx",
"field": "location",
"type": "geo",
"status": "created"
}
POST
/_api/database/:db/geo/:collection/:field/near
Find documents near a coordinate.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| lat | float | Latitude. | Yes |
| lon | float | Longitude. | Yes |
| limit | integer | Max results. Default: 10. | No |
Response
200 OK
application/json
{
"results": [
{ "document": { "_key": "...", "location": [34.05, -118.25] }, "distance": 123.45 },
{ "document": { "_key": "...", "location": [34.06, -118.26] }, "distance": 234.56 }
],
"count": 2
}
POST
/_api/database/:db/geo/:collection/:field/within
Find documents within a radius.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| lat | float | Latitude. | Yes |
| lon | float | Longitude. | Yes |
| radius | float | Radius in meters (approx). | Yes |
Response
200 OK
application/json
{
"results": [
{ "_key": "...", "location": [34.05, -118.25] },
{ "_key": "...", "location": [34.06, -118.26] }
],
"count": 2
}
Lua Scripts Management
POST
/_api/database/:db/scripts
Register a new Lua script.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| name | string | Friendly name of the script. | Yes |
| path | string | URL path segment (e.g. "greet"). | Yes |
| methods | array | Allowed HTTP methods (["GET", "POST"]). | Yes |
| code | string | The Lua source code. | Yes |
{"name": "Greeter", "path": "greet", "methods": ["GET"], "code": "return {msg='hi'}"}
Response
200 OK
application/json
{
"id": "script_123",
"name": "Greeter",
"path": "greet",
"status": "created"
}
GET
/_api/database/:db/scripts
List all registered scripts.
Response
200 OK
application/json
{
"scripts": [
{ "id": "script_123", "name": "Greeter", "path": "greet", "methods": ["GET"] }
]
}
PUT
/_api/database/:db/scripts/:id
Update an existing script.
DELETE
/_api/database/:db/scripts/:id
Delete a script.
Binary Data (Blobs)
POST
/_api/blob/:db/:collection
Upload a blob.
Request Body Options
Requires multipart/form-data with a single field named file containing the binary data.
Response
201 Created
application/json
{
"_key": "blob_123",
"filename": "image.jpg",
"size": 123456,
"mime_type": "image/jpeg"
}
GET
/_api/blob/:db/:collection/:key
Download a blob.
Response
200 OK
application/octet-stream
// Binary file content
DELETE
/_api/database/:db/document/:collection/:key
Delete a blob.
Uses the standard document deletion endpoint. This removes the metadata document and cleans up the associated binary data from storage.
Response
204 No Content
Transactions
POST
/_api/database/:db/transaction/begin
Begin a new transaction.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| isolationLevel | string | Isolation level: read_committed (default), read_uncommitted, repeatable_read, serializable. |
No |
Response
200 OK
application/json
{
"tx_id": "transaction_123",
"status": "active",
"isolation_level": "read_committed"
}
POST
/_api/database/:db/transaction/:tx_id/commit
Commit a transaction.
No request body required.
Response
200 OK
application/json
{
"tx_id": "transaction_123",
"status": "committed",
"operations_count": 5
}
POST
/_api/database/:db/transaction/:tx_id/rollback
Rollback a transaction.
No request body required.
Response
200 OK
application/json
{
"tx_id": "transaction_123",
"status": "rolled_back"
}
Cluster
GET
/_api/cluster/status
Get cluster node status and peers.
Response
200 OK
application/json
{
"node_id": "node_1",
"status": "cluster",
"peers": [ ... ],
"stats": { ... }
}
GET
/_api/cluster/info
Get general cluster information.
Response
200 OK
application/json
{
"node_id": "node_1",
"is_cluster_mode": true,
"cluster_config": { ... }
}
POST
/_api/cluster/remove-node
Remove a node from the cluster.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| node_address | string | Address of the node to remove (e.g. "localhost:6775"). | Yes |
Response
200 OK
application/json
{
"success": true,
"message": "Node removed...",
"removed_node": "localhost:6775",
"remaining_nodes": [ ... ]
}
POST
/_api/cluster/rebalance
Trigger manual cluster rebalancing.
GET
/_api/cluster/status/ws
WebSocket endpoint for live cluster status updates.
Authentication
On first startup, an admin user is created with a randomly generated password shown in the server logs. Save this password!
POST
/auth/login
Authenticate and receive a JWT token.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| username | string | Username (e.g., "admin"). | Yes |
| password | string | User's password. | Yes |
Response
200 OK
application/json
{
"token": "eyJhbGciOiJIUzI1NiIsInR..."
}
PUT
/_api/auth/password
Change current user's password.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| current_password | string | Current password. | Yes |
| new_password | string | New password. | Yes |
Response
200 OK
application/json
{
"status": "password_updated"
}
POST
/_api/auth/api-keys
Create a new API key.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| name | string | Name/Description for the API key. | Yes |
Response
200 OK
application/json
{
"id": "uuid-v4-...",
"name": "My API Key",
"key": "sk_...",
"created_at": "2023-..."
}
GET
/_api/auth/api-keys
List active API keys.
Response
200 OK
application/json
{
"keys": [
{ "id": "...", "name": "...", "created_at": "..." }
]
}
DELETE
/_api/auth/api-keys/:key_id
Revoke an API key.
Response
200 OK
application/json
{
"deleted": true
}