The web UI exposes a REST API for managing collections, documents, and retrieving metrics. All endpoints return JSON responses.
Base URL
When the web server is running, all endpoints are available at:
Authentication
The current implementation does not include authentication. The API is intended for local development and trusted environments.
For production deployments, use a reverse proxy with authentication (Basic Auth, OAuth, API keys) in front of the web server.
Health and metrics
Health check
Check if the server is running.
Server status, always returns "ok"
Get metrics
Retrieve current database metrics.
Total number of transactions started
Total number of transactions committed
Total number of transactions aborted
Currently active transactions
Percentage of transactions committed (0.0 to 1.0)
Number of transaction conflicts detected
Cache hit rate percentage (0.0 to 1.0)
Current number of dirty pages in cache
Total bytes written to WAL
Number of checkpoints completed
Number of I/O errors encountered
{
"transactions_begun": 6,
"transactions_committed": 6,
"transactions_aborted": 0,
"active_transactions": 0,
"total_transactions": 6,
"commit_rate": 1.0,
"batches_committed": 0,
"total_batched_txs": 0,
"max_batch_size": 0,
"avg_batch_size": 0.0,
"avg_batch_time_micros": 0.0,
"pages_allocated": 12,
"pages_freed": 0,
"cache_hits": 42,
"cache_misses": 18,
"cache_total_requests": 60,
"cache_hit_rate": 0.7,
"dirty_pages": 0,
"wal_writes": 6,
"wal_bytes_written": 4096,
"checkpoints": 0,
"documents_inserted": 50,
"documents_updated": 5,
"documents_deleted": 0,
"documents_read": 55,
"total_document_operations": 110,
"io_errors": 0,
"transaction_conflicts": 0
}
Collections
List collections
Retrieve all collection names, sorted alphabetically.
Response
[
"blog_posts",
"orders",
"products",
"users"
]
Create collection
Create a new collection.
Name of the collection to create. Must contain only letters, numbers, and underscores.
Name of the created collection
{
"status": "created",
"name": "customers"
}
Rename collection
Rename an existing collection.
PATCH /api/collections/{collection_name}
Current name of the collection
New name for the collection
{
"new_name": "premium_customers"
}
{
"status": "renamed",
"old_name": "customers",
"new_name": "premium_customers"
}
Delete collection
Delete a collection and all its documents.
DELETE /api/collections/{collection_name}
Name of the collection to delete
Name of the deleted collection
{
"status": "deleted",
"name": "customers"
}
Deleting a collection is permanent and cannot be undone. All documents in the collection will be deleted.
Documents
List documents
Retrieve all documents in a collection.
GET /api/collections/{collection_name}
[
{
"_id": "01JKXM7Z3Q9YHNJ5TC4K8WFP2E",
"name": "Alice",
"email": "[email protected]",
"age": 30,
"role": "admin"
},
{
"_id": "01JKXM7Z3RBKP4M2QW6N7X8Y9Z",
"name": "Bob",
"email": "[email protected]",
"age": 25,
"role": "user"
}
]
Create document
Insert a new document into a collection.
POST /api/collections/{collection_name}
JSON document to insert. The _id field will be automatically generated if not provided.
{
"name": "Charlie",
"email": "[email protected]",
"age": 28,
"role": "moderator",
"preferences": {
"theme": "dark",
"notifications": true
}
}
The generated document ID (ULID format)
{
"id": "01JKXM7Z3SCMT5N3RX7P8A9BC1"
}
Update document
Update an existing document by ID.
PUT /api/collections/{collection_name}/{document_id}
Updated document content. The _id field cannot be changed.
{
"_id": "01JKXM7Z3SCMT5N3RX7P8A9BC1",
"name": "Charlie Brown",
"email": "[email protected]",
"age": 29,
"role": "admin",
"preferences": {
"theme": "light",
"notifications": false
}
}
Updates replace the entire document. To update specific fields, send the complete document with only the desired fields changed.
Delete document
Delete a document by ID.
DELETE /api/collections/{collection_name}/{document_id}
Error responses
All error responses follow this format:
404 Not Found
Returned when a collection or document doesn’t exist.
500 Internal Server Error
Failed to create collection: collection already exists
Example usage
Using curl
curl http://127.0.0.1:8080/metrics
Using JavaScript
// Fetch metrics
const metrics = await fetch('http://127.0.0.1:8080/metrics')
.then(res => res.json());
console.log(`Cache hit rate: ${(metrics.cache_hit_rate * 100).toFixed(1)}%`);
console.log(`Documents inserted: ${metrics.documents_inserted}`);
// Create a document
const response = await fetch('http://127.0.0.1:8080/api/collections/users', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
name: 'Bob',
email: '[email protected]',
age: 25
})
});
const result = await response.json();
console.log(`Created document: ${result.id}`);
// List all documents
const users = await fetch('http://127.0.0.1:8080/api/collections/users')
.then(res => res.json());
console.log(`Found ${users.length} users`);
Using Python
import requests
import json
BASE_URL = 'http://127.0.0.1:8080'
# Get metrics
metrics = requests.get(f'{BASE_URL}/metrics').json()
print(f"Active transactions: {metrics['active_transactions']}")
print(f"Cache hit rate: {metrics['cache_hit_rate'] * 100:.1f}%")
# Create collection
requests.post(
f'{BASE_URL}/api/collections',
json={'name': 'products'}
)
# Insert document
response = requests.post(
f'{BASE_URL}/api/collections/products',
json={
'name': 'Laptop',
'price': 999.99,
'in_stock': True
}
)
doc_id = response.json()['id']
print(f"Created document: {doc_id}")
# Get all documents
products = requests.get(f'{BASE_URL}/api/collections/products').json()
for product in products:
print(f"{product['name']}: ${product['price']}")
Next steps