API Reference

Retrieve a secret value. Increments the read counter. Burns or seals the record if the read limit is reached.

// 200
{ "key": "DB_URL", "value": "postgres://..." }

// 404 — expired, burned, or not found
// 410 — sealed (delete=false, reads exhausted)

Returns metadata via headers. Does not increment the read counter.

X-Sirr-Read-Count: 3
X-Sirr-Reads-Remaining: 7    (or "unlimited")
X-Sirr-Delete: false
X-Sirr-Created-At: 1700000000
X-Sirr-Expires-At: 1700003600  (if TTL set)
X-Sirr-Status: active          (or "sealed")

// 200, 404 (not found), or 410 (sealed)

Health check endpoint.

{ "status": "ok" }

Create a new secret.

// Request
{
  "key": "DB_URL",
  "value": "postgres://...",
  "ttl_seconds": 3600,
  "max_reads": 1,
  "delete": true
}
// delete defaults to true. Set false for patchable secrets.

// 201
{ "key": "DB_URL" }

// 402 — license required (>100 secrets without SIRR_LICENSE_KEY)

Update value, max_reads, or TTL. Only works on delete=false secrets. Resets read_count to 0.

// Request (all fields optional)
{
  "value": "new-value",
  "max_reads": 10,
  "ttl_seconds": 3600
}

// 200 — updated metadata
// 404 — not found or expired
// 409 — cannot patch a delete=true secret

List all secrets. Metadata only — values are never included.

{
  "secrets": [
    {
      "key": "DB_URL",
      "created_at": 1700000000,
      "expires_at": 1700003600,
      "max_reads": 1,
      "read_count": 0,
      "delete": true
    }
  ]
}

Delete a secret immediately.

{ "deleted": true }

Delete all expired secrets.

{ "pruned": 3 }