MantleDB

Locks a namespace and returns a one-time secret key. The key is hashed before storage — save it immediately, it cannot be reconstructed. Once claimed, all writes to this namespace require X-Mantle-Key. Claiming also extends your data retention from 30 to 90 days of inactivity.

Pass ?email= to register a recovery address at claim time. If you lose the key, you can request a reset link via Key Recovery.

# Basic claim
curl https://mantledb.sh/v2/claim/my-app

# With a recovery email (recommended)
curl "https://mantledb.sh/v2/claim/[email protected]"

# Response
{
  "success": true,
  "namespace": "my-app",
  "key": "a3f9...",
  "warning": "SAVE THIS KEY. It cannot be recovered."
}

Returns all paths stored in a namespace along with each entry's public_read flag and last-updated timestamp. Without a key, only public_read: true entries are returned.

curl https://mantledb.sh/v2/list/my-app \
  -H "X-Mantle-Key: YOUR_KEY"

# Response
{
  "namespace": "my-app",
  "entries": [
    { "path": "config",      "public_read": 1, "updated_at": 1748000000000 },
    { "path": "users/alice", "public_read": 0, "updated_at": 1748000001000 }
  ]
}

Creates or fully overwrites a JSON entry at the given path. Paths can be as deep as you need — /v2/my-app/users/alice/settings works without any upfront setup. If you only want to update certain fields, use PATCH instead.

# Entry expires in 1 hour
curl -X POST "https://mantledb.sh/v2/my-app/session/abc123?ttl=3600" \
  -H "Content-Type: application/json" \
  -H "X-Mantle-Key: YOUR_KEY" \
  -d '{"userId": 42, "token": "..."}'

# Response includes when it will expire
{"success": true, "path": "session/abc123", "expires_at": 1748003600000}

curl -X POST https://mantledb.sh/v2/my-app/users/alice \
  -H "Content-Type: application/json" \
  -H "X-Mantle-Key: YOUR_KEY" \
  -d '{"name": "Alice", "status": "online", "role": "admin"}'

Returns the stored JSON for the given path. On a claimed namespace, a key is required unless that entry has public_read enabled. Use the ?key= query param to read a single top-level field — useful for lightweight polling without transferring the full object.

# Full entry
curl https://mantledb.sh/v2/my-app/users/alice \
  -H "X-Mantle-Key: YOUR_KEY"
# → {"name": "Alice", "status": "online", "role": "admin"}

# Single field — no need to fetch the whole object
curl "https://mantledb.sh/v2/my-app/users/alice?key=status"
# → {"status": "online"}

Merges the request body into the existing entry using JSON Merge Patch (RFC 7396). Only the fields you send are changed — all other fields are untouched. Set a field to null to remove it entirely.

# alice is currently: {"name": "Alice", "status": "online", "role": "admin"}

curl -X PATCH https://mantledb.sh/v2/my-app/users/alice \
  -H "Content-Type: application/json" \
  -H "X-Mantle-Key: YOUR_KEY" \
  -d '{"status": "away", "lastSeen": 1748000000}'

# alice is now: {"name": "Alice", "status": "away", "role": "admin", "lastSeen": 1748000000}

# Remove a field by setting it to null
# -d '{"role": null}'  →  removes the role field entirely

Atomically increments (or decrements) a numeric field in an existing entry. The operation runs inside a transaction — safe for concurrent updates from multiple clients. If the entry doesn't exist yet, it is created with the field set to 0 before incrementing.

curl -X POST https://mantledb.sh/v2/increment/my-app/stats \
  -H "Content-Type: application/json" \
  -H "X-Mantle-Key: YOUR_KEY" \
  -d '{"key": "views", "by": 1}'

# Response
{"success": true, "views": 42}

# Use a negative value to decrement
# -d '{"key": "views", "by": -1}'

Permanently removes a single entry. Returns 404 if the path does not exist.

curl -X DELETE https://mantledb.sh/v2/my-app/users/alice \
  -H "X-Mantle-Key: YOUR_KEY"

# Response
{"success": true, "message": "Entry deleted"}

Toggles the public_read flag on a specific entry. When enabled, anyone can read that entry without a key — even if the rest of the namespace is private. This lets you expose individual endpoints (a public config, a leaderboard, an API status) while keeping everything else locked down. Writes always require the key regardless of this setting.

# Make a single entry publicly readable
curl -X PUT https://mantledb.sh/v2/visibility/my-app/config \
  -H "Content-Type: application/json" \
  -H "X-Mantle-Key: YOUR_KEY" \
  -d '{"public_read": true}'

# Now anyone can read it — no key required
curl https://mantledb.sh/v2/my-app/config

# Revert to private
curl -X PUT https://mantledb.sh/v2/visibility/my-app/config \
  -H "Content-Type: application/json" \
  -H "X-Mantle-Key: YOUR_KEY" \
  -d '{"public_read": false}'

Downloads every entry in the namespace as a single JSON object, keyed by path. Useful for backups, migrations, or seeding another system. Requires the namespace key on claimed namespaces.

curl https://mantledb.sh/v2/export/my-app \
  -H "X-Mantle-Key: YOUR_KEY"

# Response
{
  "namespace": "my-app",
  "exported_at": "2026-03-17T12:00:00.000Z",
  "entry_count": 3,
  "entries": {
    "config":       {"theme": "dark", "lang": "en"},
    "users/alice":  {"name": "Alice", "role": "admin"},
    "users/bob":    {"name": "Bob",   "role": "viewer"}
  }
}

Creates a Stripe Checkout session and returns a URL to complete payment. Credits are denominated in days — one unit of purchase equals 30 credits (30 days). The scavenger burns one credit per day; while credits remain, your namespace is exempt from the inactivity reaper and your limits are upgraded.

# Get a checkout URL — opens in browser or redirect from your app
curl "https://mantledb.sh/v2/upgrade/my-app?quantity=3"
# → {"url": "https://checkout.stripe.com/..."}

# quantity = number of 30-day blocks (1–12). Defaults to 1.
# Credits are added automatically after payment completes.

Returns a list of past snapshots for the given entry, newest first. A snapshot is saved automatically before every overwrite on a pro namespace — up to 10 versions are kept per entry. Versions include an id you can pass to /v2/restore.

curl https://mantledb.sh/v2/history/my-app/users/alice \
  -H "X-Mantle-Key: YOUR_KEY"

# Response
{
  "path": "users/alice",
  "versions": [
    { "id": 42, "created_at": 1748001000000 },
    { "id": 37, "created_at": 1747900000000 }
  ]
}

Restores an entry to a specific version. The current data is snapshotted before the restore (so it's recoverable too). Returns the restored data.

curl -X POST https://mantledb.sh/v2/restore/my-app/users/alice \
  -H "Content-Type: application/json" \
  -H "X-Mantle-Key: YOUR_KEY" \
  -d '{"version_id": 37}'

# Response
{
  "success": true,
  "path": "users/alice",
  "restored": {"name": "Alice", "role": "viewer"}
}

Registers a webhook URL that will receive a POST request whenever an entry in the namespace is written to or deleted. Up to 5 webhooks per namespace. The URL must use https://.

Optionally pass a secret — if set, each request will include an X-Mantle-Signature: sha256=<hmac> header so you can verify the payload.

# Register a webhook
curl -X POST https://mantledb.sh/v2/webhooks/my-app \
  -H "Content-Type: application/json" \
  -H "X-Mantle-Key: YOUR_KEY" \
  -d '{"url": "https://my-server.com/hooks/mantle", "events": "write,delete", "secret": "opt-sig-key"}'

# Response
{"id": "a1b2c3...", "url": "https://my-server.com/hooks/mantle", "events": "write,delete"}

# List webhooks
curl https://mantledb.sh/v2/webhooks/my-app \
  -H "X-Mantle-Key: YOUR_KEY"

# Delete a webhook
curl -X DELETE https://mantledb.sh/v2/webhooks/my-app/a1b2c3... \
  -H "X-Mantle-Key: YOUR_KEY"