REST API for encrypted secret sharing

Create and retrieve encrypted, self-destructing secrets programmatically.

This API stores pre-encrypted ciphertext. Encryption must happen client-side before calling the API. The server never sees plaintext.

For most use cases, the CLI or GitHub Action handle encryption automatically.

Base URL

https://www.vaulted.fyi/api

POST/api/secrets

Store encrypted ciphertext with expiration and view-limit metadata. Returns a secret ID.

Request body

Field	Type	Required	Values
ciphertext	string	yes	max 4096 chars
iv	string	yes	initialization vector
maxViews	number	yes	0, 1, 3, 5, 10 (0 = unlimited, returns -1 for viewsRemaining)
ttl	number	yes	3600, 86400, 604800, 2592000 (seconds)
hasPassphrase	boolean	no	default false

Example request

curl -X POST https://www.vaulted.fyi/api/secrets \
  -H "Content-Type: application/json" \
  -d '{
    "ciphertext": "encrypted-base64-data",
    "iv": "initialization-vector",
    "maxViews": 1,
    "ttl": 86400,
    "hasPassphrase": false
  }'

Response

{ "id": "abc123" }

Error responses

Status	Description
400	Validation error (missing or invalid fields)
429	Rate limit exceeded
500	Internal server error

GET/api/secrets/[id]

Retrieve encrypted ciphertext and consume a view. The secret is deleted when all views are consumed.

Each request consumes one view. Use the status endpoint to check without consuming.

Example request

curl https://www.vaulted.fyi/api/secrets/abc123

Response

{
  "ciphertext": "encrypted-base64-data",
  "iv": "initialization-vector",
  "hasPassphrase": false,
  "viewsRemaining": 2
}

viewsRemaining is -1 for unlimited-view secrets (maxViews = 0).

Error responses

Status	Description
404	Secret not found or expired
429	Rate limit exceeded
500	Internal server error

GET/api/secrets/[id]/status

Check if a secret exists and how many views remain without consuming a view.

Example request

curl https://www.vaulted.fyi/api/secrets/abc123/status

Response

{
  "exists": true,
  "viewsRemaining": 3,
  "hasPassphrase": false
}

viewsRemaining is -1 for unlimited-view secrets (maxViews = 0).

Error responses

Status	Description
404	Secret not found or expired
500	Internal server error

Rate limits

Endpoint	Limit	Window
POST /api/secrets	20 requests	10 minutes
GET /api/secrets/[id]	60 requests	10 minutes

Rate limits are per IP address. Exceeding the limit returns 429.

Use the CLI for encrypted secret sharing from the terminal

Use the GitHub Action for CI/CD workflows

or use the web app