V1.0.0-BETA
encrypted-at-rest
no-accounts
json-only

MANTLEDB

MantleDB is anonymous JSON storage for tiny apps, scripts, and automations. You get an Account ID (AID) and you can PUT/GET JSON into named buckets. No email. No password. No dashboard. Just an API that does one thing.

Important:
Your AID is your only key. Lose it and your data is unrecoverable. That’s the deal. That’s also why it’s so simple.
Quickstart Documentation Limits & Pricing

What it is

  • • A tiny “backend” for small apps that just need JSON persistence.
  • • A place to stash settings, state, or cached responses.
  • • A dead-simple target for curl, cron jobs, n8n, Zapier-like tools, etc.
  • • Encrypted at rest (server-side), stored per bucket.

What it isn’t

  • • Not a database for big apps.
  • • Not file hosting. (Max payload: 1MB)
  • • Not collaborative editing or patching (yet / maybe never).
  • • Not recoverable. There’s no “reset password” because there is no password.

Anonymous

No email required. Your AID is the only thing linking you to your data. Treat it like an API key.

Buckets

A bucket is just a named JSON blob. Buckets are created on first write. No schema. No migrations. Just JSON.

Scriptable

Works clean with curl, bash, cron, n8n, CI pipelines, and quick prototype apps. Send JSON, get JSON.

Quickstart

Get an Account ID, write JSON to a bucket, read it back anywhere. That’s basically the product.

1) Generate an Account ID (AID) 

curl -s https://api.mantledb.sh/api/auth/register

Save the returned aid. Copy it into a password manager or env var.

2) Store JSON in a bucket 

curl -s -X POST https://api.mantledb.sh/api/b/YOUR_AID/my-settings \
  -H "Content-Type: application/json" \
  -d '{"theme":"dark","notifications":true}'

3) Retrieve it

curl -s https://api.mantledb.sh/api/b/YOUR_AID/my-settings

4) Check your status / limits 

curl -s https://api.mantledb.sh/api/auth/status/YOUR_AID

Limits & Pricing

Free

  • • 1 bucket
  • • Bucket wiped after 48 hours of inactivity
  • • Max payload: 1MB per write
  • • Good for testing / scratch storage

Pro

  • • More buckets (configurable cap)
  • • No scavenger wipes
  • • Same 1MB payload limit
  • • For small apps that need persistence without running a DB

Checkout (Stripe hosted):

curl -L https://api.mantledb.sh/api/auth/upgrade/YOUR_AID?quantity=1

1 quantity = 30 days of Pro time.

Documentation

Concepts

Account ID (AID): a single identifier that acts like your API key. There is no login.

Bucket ID (BID): the name of a bucket. A bucket stores exactly one JSON object (upsert).

Tip: keep bucket names URL-safe. Example: my-settings, cache-weather, app-state.

Endpoints

GET /api/auth/register

Generates a new anonymous identity and returns your aid. Store it. Don’t lose it. 

{
  "success": true,
  "aid": "1234567890123456",
  "metadata": { "tier": "free", "bucket_limit": 1 },
  "instructions": "Store this AID securely..."
}

POST /api/b/:aid/:bid

Upserts JSON into a bucket. Buckets are created on first write. Payload limit: 1MB. 

curl -X POST https://api.mantledb.sh/api/b/YOUR_AID/my-bucket \
  -H "Content-Type: application/json" \
  -d '{"hello":"world"}'

GET /api/b/:aid/:bid

Reads the bucket JSON. Returns 404 if missing or scavenged. 

curl https://api.mantledb.sh/api/b/YOUR_AID/my-bucket

GET /api/auth/status/:aid

Returns your tier, bucket usage, and remaining Pro time. 

curl https://api.mantledb.sh/api/auth/status/YOUR_AID

GET /api/auth/upgrade/:aid?quantity=1

Redirects to Stripe checkout. 1 quantity = 30 days of Pro. 

curl -L https://api.mantledb.sh/api/auth/upgrade/YOUR_AID?quantity=1

POST /api/auth/redeem/:aid?code=YOUR_CODE

Redeem a promo code for Pro time. 

curl -X POST "https://api.mantledb.sh/api/auth/redeem/YOUR_AID?code=BUENA-VISTA-FREE"

Errors & Responses

MantleDB uses boring HTTP status codes + a predictable JSON body.

Invalid account
{
  "success": false,
  "error": "INVALID_ACCOUNT",
  "message": "That Account ID does not exist."
}
Limit reached
{
  "success": false,
  "error": "LIMIT_REACHED",
  "message": "Free tier limit of 1 buckets reached."
}
Not found
{
  "success": false,
  "error": "NOT_FOUND",
  "message": "No bucket found with the name 'my-bucket' for this account."
}
Empty payload
{
  "success": false,
  "error": "EMPTY_PAYLOAD",
  "message": "You must provide a JSON object in the request body."
}

Data lifecycle (the scavenger)

Free tier buckets are automatically deleted after a period of inactivity. Pro buckets are not scavenged.

  • • A bucket’s “last activity” is its last write time.
  • • Scavenger runs periodically and purges expired free buckets.
  • • Accounts with no buckets may also be cleaned up after a time window.

Copy/paste patterns

Use an env var
export MANTLE_AID="YOUR_AID"

curl -s -X POST "https://api.mantledb.sh/api/b/$MANTLE_AID/app-state" \
  -H "Content-Type: application/json" \
  -d '{"loggedIn":true,"count":42}'
Store a cached API response 
curl -s "https://some-api.com/thing" | \
  jq '.' | \
  curl -s -X POST "https://api.mantledb.sh/api/b/$MANTLE_AID/cache-thing" \
    -H "Content-Type: application/json" \
    -d @-

(Assumes you have jq. This is the “small app backend” vibe in one snippet.)