REST API reference

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:

http://127.0.0.1:8080

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.

GET /health

status

string

Server status, always returns "ok"

Response

{
  "status": "ok"
}

Get metrics

Retrieve current database metrics.

GET /metrics

transactions_begun

number

Total number of transactions started

transactions_committed

number

Total number of transactions committed

transactions_aborted

number

Total number of transactions aborted

active_transactions

number

Currently active transactions

commit_rate

number

Percentage of transactions committed (0.0 to 1.0)

transaction_conflicts

number

Number of transaction conflicts detected

cache_hit_rate

number

Cache hit rate percentage (0.0 to 1.0)

cache_hits

number

Number of cache hits

cache_misses

number

Number of cache misses

dirty_pages

number

Current number of dirty pages in cache

pages_allocated

number

Total pages allocated

pages_freed

number

Total pages freed

wal_writes

number

Number of WAL writes

wal_bytes_written

number

Total bytes written to WAL

checkpoints

number

Number of checkpoints completed

documents_inserted

number

Total documents inserted

documents_updated

number

Total documents updated

documents_deleted

number

Total documents deleted

documents_read

number

Total documents read

io_errors

number

Number of I/O errors encountered

Response

{
  "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.

GET /api/collections

Response

[
  "blog_posts",
  "orders",
  "products",
  "users"
]

Create collection

Create a new collection.

POST /api/collections

name

string

required

Name of the collection to create. Must contain only letters, numbers, and underscores.

Request

{
  "name": "customers"
}

status

string

Always returns "created"

name

string

Name of the created collection

Response (201 Created)

{
  "status": "created",
  "name": "customers"
}

Rename collection

Rename an existing collection.

PATCH /api/collections/{collection_name}

collection_name

string

required

Current name of the collection

new_name

string

required

New name for the collection

Request

{
  "new_name": "premium_customers"
}

status

string

Always returns "renamed"

old_name

string

Previous collection name

new_name

string

New collection name

Response

{
  "status": "renamed",
  "old_name": "customers",
  "new_name": "premium_customers"
}

Delete collection

Delete a collection and all its documents.

DELETE /api/collections/{collection_name}

collection_name

string

required

Name of the collection to delete

status

string

Always returns "deleted"

name

string

Name of the deleted collection

Response

{
  "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}

collection_name

string

required

Name of the collection

Response

[
  {
    "_id": "01JKXM7Z3Q9YHNJ5TC4K8WFP2E",
    "name": "Alice",
    "email": "alice@example.com",
    "age": 30,
    "role": "admin"
  },
  {
    "_id": "01JKXM7Z3RBKP4M2QW6N7X8Y9Z",
    "name": "Bob",
    "email": "bob@example.com",
    "age": 25,
    "role": "user"
  }
]

Create document

Insert a new document into a collection.

POST /api/collections/{collection_name}

collection_name

string

required

Name of the collection

document

object

required

JSON document to insert. The _id field will be automatically generated if not provided.

Request

{
  "name": "Charlie",
  "email": "charlie@example.com",
  "age": 28,
  "role": "moderator",
  "preferences": {
    "theme": "dark",
    "notifications": true
  }
}

string

The generated document ID (ULID format)

Response (201 Created)

{
  "id": "01JKXM7Z3SCMT5N3RX7P8A9BC1"
}

Update document

Update an existing document by ID.

PUT /api/collections/{collection_name}/{document_id}

collection_name

string

required

Name of the collection

document_id

string

required

Document ID (ULID)

document

object

required

Updated document content. The _id field cannot be changed.

Request

{
  "_id": "01JKXM7Z3SCMT5N3RX7P8A9BC1",
  "name": "Charlie Brown",
  "email": "charlie.brown@example.com",
  "age": 29,
  "role": "admin",
  "preferences": {
    "theme": "light",
    "notifications": false
  }
}

status

string

Always returns "updated"

Response

{
  "status": "updated"
}

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}

collection_name

string

required

Name of the collection

document_id

string

required

Document ID to delete

status

string

Always returns "deleted"

Response

{
  "status": "deleted"
}

Error responses

All error responses follow this format: 404 Not Found

Not Found

Returned when a collection or document doesn’t exist. 500 Internal Server Error

Failed to create collection: collection already exists

Returned when an operation fails. The response body contains the error message.

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: 'bob@example.com',
    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

Web UI overview - Learn about the dashboard interface
Metrics - Understanding database metrics
Observability - Advanced monitoring patterns

Command Line

Web UI

Monitoring

Base URL

Authentication

Health and metrics

Health check

Get metrics

Collections

List collections

Create collection

Rename collection

Delete collection

Documents

List documents

Create document

Update document

Delete document

Error responses

Example usage

Using curl

Using JavaScript

Using Python

Next steps

Build docs developers (and LLMs) love

Command Line

Web UI

Monitoring

Documentation Index

​Base URL

​Authentication

​Health and metrics

​Health check

​Get metrics

​Collections

​List collections

​Create collection

​Rename collection

​Delete collection

​Documents

​List documents

​Create document

​Update document

​Delete document

​Error responses

​Example usage

​Using curl

​Using JavaScript

​Using Python

​Next steps

Build docs developers (and LLMs) love

Base URL

Authentication

Health and metrics

Health check

Get metrics

Collections

List collections

Create collection

Rename collection

Delete collection

Documents

List documents

Create document

Update document

Delete document

Error responses

Example usage

Using curl

Using JavaScript

Using Python

Next steps