API Documentation

Complete reference for all WrenDB endpoints

Base URL: https://wrendb.com/api

WrenDB Principles

Public reads by default

Anyone can read stored data with just the key. No authentication required.

Private writes with a master token

Only the stash owner can update or delete items using their master token.

30-day TTL on everything

Data auto-expires after 30 days from creation. No cleanup required.

Simple HTTP interface

Just GET, POST, PUT, DELETE. No SDKs, no complicated protocols.

Authentication

Create Read Update Delete List
Stash Public — — Token Auth Token Auth
Item Public Public Token Auth Token Auth —
Presigned URL Token Auth — Public — —
Authorization Format 
Authorization: Bearer <master_token>

Stash Endpoints

Stashes organize related items. Each stash has a master token that controls all its items.

POST /stash

Create Stash

Create a new stash to organize related items. Each stash has a fixed limit of 100 items. Receive a master token to control the stash and all its items.

Important: Your master_token is shown only once. There's no way to recover it, so write it down!

Request

HTTP 
POST /stash
Content-Type: application/json

{
  "name": "My Stash",           // Optional
  "description": "..."          // Optional
}

Response (200)

JSON 
{
  "stash_id": "stash-abc123...",
  "master_token": "token-xyz789...",
  "message": "Save this token securely. It will not be shown again and is not recoverable. Your stash has a limit of 100 items."
}

Example

curl 
curl -X POST https://wrendb.com/api/stash \
  -H "Content-Type: application/json" \
  -d '{"name": "Session Storage", "description": "User session data"}'
GET /stash/{stash_id}/items

List Stash Items

List all items in a stash. Requires your master token for authentication.

Request

HTTP 
GET /stash/{stash_id}/items
Authorization: Bearer <master_token>

Response (200)

JSON 
{
  "stash_id": "stash-abc123...",
  "items": [
    {
      "key": "key-def456...",
      "value": "stored data",
      "stash_id": "stash-abc123...",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 1
}

Possible Errors

  • 401 Missing authorization header
  • 403 Invalid master token
  • 404 Stash not found

Example

curl 
curl https://wrendb.com/api/stash/stash-abc123/items \
  -H "Authorization: Bearer token-xyz789..."
POST /stash/{stash_id}/item

Create Item in Stash

Add a new item to a stash. No authentication required – anyone who knows the stash ID can add items!

Note: No authentication required! This allows public collaboration use cases like forms, surveys, and data collection.

Request

HTTP 
POST /stash/{stash_id}/item
Content-Type: text/plain

<your value as plain text>

Response (200)

JSON 
{
  "key": "key-def456...",
  "message": "Item created successfully in stash"
}

Possible Errors

  • 403 Item limit reached
  • 404 Stash not found

Example

curl 
curl -X POST https://wrendb.com/api/stash/stash-abc123/item \
  -H "Content-Type: text/plain" \
  -d "Hello, World!"
DELETE /stash/{stash_id}

Delete Stash

Delete a stash and all its items permanently. Requires your master token.

Request

HTTP 
DELETE /stash/{stash_id}
Authorization: Bearer <master_token>

Response (200)

JSON 
{
  "success": true,
  "message": "Stash and all items deleted successfully"
}

Possible Errors

  • 401 Missing authorization
  • 403 Invalid master token
  • 404 Stash not found

Example

curl 
curl -X DELETE https://wrendb.com/api/stash/stash-abc123 \
  -H "Authorization: Bearer token-xyz789..."

Item Endpoints

Items are key-value pairs. Reading requires no auth, but updates/deletes need the stash's master token.

GET /item/{key}

Get Value

Retrieve a value by its key. No authentication required.

Request

HTTP 
GET /item/{key}

Response (200)

text/plain 
<the stored value>

Possible Errors

  • 404 Key not found

Example

curl 
curl https://wrendb.com/api/item/key-abc123
PUT /item/{key}

Update Value

Update an existing value. Requires your master token for authentication.

Request

HTTP 
PUT /item/{key}
Authorization: Bearer <master_token>
Content-Type: text/plain

<new value>

Response (200)

JSON 
{
  "success": true,
  "message": "Value updated successfully"
}

Possible Errors

  • 401 Missing authorization – where's your token?
  • 403 Wrong token for this nest
  • 404 Key not found

Example

curl 
curl -X PUT https://wrendb.com/api/item/key-abc123 \
  -H "Authorization: Bearer token-xyz789..." \
  -H "Content-Type: text/plain" \
  -d "Updated value"
DELETE /item/{key}

Delete Key-Value Pair

Delete a key-value pair permanently. Requires your master token.

Request

HTTP 
DELETE /item/{key}
Authorization: Bearer <master_token>

Response (200)

JSON 
{
  "success": true,
  "message": "Key deleted successfully"
}

Possible Errors

  • 401 Missing authorization
  • 403 Invalid master token
  • 404 Key not found

Example

curl 
curl -X DELETE https://wrendb.com/api/item/key-abc123 \
  -H "Authorization: Bearer token-xyz789..."
POST /item/{key}/presign

Create Presigned Update URL

Generate a temporary URL that allows others to update your data without sharing your master token. Expires in 15 minutes.

Request

HTTP 
POST /item/{key}/presign
Authorization: Bearer <master_token>
Content-Type: text/plain

<value to set when URL is called>

Response (200)

JSON 
{
  "url": "https://wrendb.com/update?token=eyJ..."
}

Possible Errors

  • 401 Missing authorization
  • 403 Invalid master token
  • 404 Key not found

Example

curl 
curl -X POST https://wrendb.com/api/item/key-abc123/presign \
  -H "Authorization: Bearer token-xyz789..." \
  -H "Content-Type: text/plain" \
  -d "New value via presigned URL"
GET /update?token={jwt}

Execute Presigned Update

Execute a presigned update URL. No authentication required – the JWT token provides authorization.

Request

HTTP 
GET /update?token=<jwt_token>

Response (200)

JSON 
{
  "success": true,
  "message": "Value updated successfully via pre-signed URL"
}

Possible Errors

  • 400 Missing token parameter
  • 401 Token expired or invalid
  • 404 Key not found

Example

curl 
curl "https://wrendb.com/update?token=eyJ..."

When Things Go Wrong

All errors follow the same JSON format:

JSON Error Format 
{
  "error": "Description of what went wrong"
}

HTTP Status Codes

Code What it means
200 Success! Everything worked.
400 Bad request – you forgot something or sent invalid data
401 Unauthorized – missing or invalid authentication
403 Forbidden – you're authenticated but this isn't your nest
404 Not found – that key doesn't exist
409 Conflict – that key already exists (shouldn't happen with UUIDs)
413 Payload too large – keep it under 100KB
429 Too many requests – rate limit exceeded
500 Internal error – something broke on our end

Examples

See practical examples and use cases: