Burn the Secret API

Documentation

The Burn the Secret API allows you to programmatically create, retrieve, and manage self-destructing secrets. Use it to securely share passwords, API keys, and sensitive information in your applications.

Overview

Burn the Secret is a secure secret-sharing service that encrypts sensitive information and generates self-destructing links. Secrets are automatically deleted after they expire or reach their view limit.

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

Content Type: All requests must use application/json

Key Features

Auto-expiring links — Set TTL from 30 minutes to 999 days
View limits — Secrets auto-delete after a set number of views
Password protection — Optional passphrase for extra security
File support — Share files up to 50MB
Burn on demand — Manually delete secrets at any time

How It Works

1. Create a secret — Send your sensitive content to the API with optional settings like TTL, view limit, and passphrase.

2. Get the secure link — The API returns a unique URL that you can share with your recipient.

3. Recipient views the secret — When they open the link, the secret is decrypted and displayed. This counts as a view.

4. Auto-destruct — Once the view limit is reached or the TTL expires, the secret is permanently deleted from our servers.

Authentication

API requests require authentication using an API key. Include your key in theAuthorizationheader:

HTTP Header

Authorization: Bearer ks_live_your_api_key

Get your API key from the API Access page in your dashboard. Keep your API key secure and never expose it in client-side code.

Create Secret

Create a new encrypted secret with customizable expiration and view limits.

POST /api/secrets

Example Request

cURL

curl -X POST https://burnthesecret.com/api/secrets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ks_live_your_api_key" \
  -d '{
    "secret": "my-super-secret-password",
    "ttl": 86400,
    "maxViews": 1,
    "passphrase": "optional-password"
  }'

Example Response

JSON

{
  "success": true,
  "metadata": {
    "key": "abc123xyz",
    "secretKey": "def456uvw",
    "ttl": 86400,
    "expiresAt": "2025-01-27T12:00:00.000Z",
    "createdAt": "2025-01-26T12:00:00.000Z",
    "hasPassphrase": true,
    "maxViews": 1,
    "viewCount": 0
  },
  "secretUrl": "https://burnthesecret.com/secret/def456uvw",
  "metadataUrl": "https://burnthesecret.com/receipt/abc123xyz",
  "requestId": "req_m4k7x2_abc123"
}

JavaScript

const response = await fetch('https://burnthesecret.com/api/secrets', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ks_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    secret: 'my-sensitive-data',
    ttl: 86400,
    maxViews: 1,
  }),
});

const data = await response.json();
console.log(data.secretUrl);

Python

import requests

response = requests.post(
    'https://burnthesecret.com/api/secrets',
    headers={
        'Authorization': 'Bearer ks_live_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'secret': 'my-sensitive-data',
        'ttl': 86400,
        'maxViews': 1,
    }
)

data = response.json()
print(data['secretUrl'])

Understanding Key Types

When you create a secret, the API returns two different keys. Understanding the difference is important:

secretKey

Used by recipients to view the secret content. Share this key (via the secretUrl) with the person who needs to see the secret. Viewing with this key increments the view count.

metadataKey (key)

Used by the sender to check status or delete the secret. This is your "receipt" - use it to see if the secret was viewed, or to burn it before the recipient sees it.

Get Secret Status

Check the status of a secret without viewing its content. Works with either key type.

GET /api/secrets/:key

Example Request

cURL

curl https://burnthesecret.com/api/secrets/abc123xyz

Example Response

JSON

{
  "exists": true,
  "type": "metadata",
  "viewed": false,
  "burned": false,
  "expiresAt": "2025-01-27T12:00:00.000Z",
  "hasPassphrase": true,
  "secretKey": "def456uvw",
  "maxViews": 1,
  "viewCount": 0,
  "viewsRemaining": 1,
  "requestId": "req_m4k9z4_ghi789"
}

Note: This endpoint does not count as a view and does not reveal the secret content.

View Secret Content

Retrieve and view a secret's content. This increments the view count and may trigger deletion if the view limit is reached. Use the secretKey (not the metadataKey).

POST /api/secrets/:secretKey

Request Body

Parameter	Type	Description
passphrase	string	Required if the secret is password-protected

Example Request

cURL

curl -X POST https://burnthesecret.com/api/secrets/def456uvw \
  -H "Content-Type: application/json" \
  -d '{"passphrase": "optional-password"}'

Example Response

JSON

{
  "success": true,
  "secret": "my-super-secret-password",
  "oneClickRetrieval": true,
  "viewsRemaining": 0,
  "requestId": "req_m4k8y3_def456"
}

Delete Secret

Permanently delete a secret before it expires. Use the metadata key (not the secret key) for deletion.

DELETE /api/secrets/:metadataKey

Example Request

cURL

curl -X DELETE https://burnthesecret.com/api/secrets/abc123xyz

Example Response

JSON

{
  "success": true,
  "message": "Secret burned successfully",
  "requestId": "req_m4kaz5_jkl012"
}

Request Parameters

Parameters for the Create Secret endpoint.

Parameter	Type	Required	Description
secret	string	Yes	The content to encrypt (max 50MB)
ttl	integer	No	Time to live in seconds. Min: 1800 (30 min), Max: 86313600 (999 days). Default: 86400 (1 day)
maxViews	integer \| null	No	Max views before deletion. 1-999, or null for unlimited. Default: 1
passphrase	string	No	Password required to view the secret
oneClickRetrieval	boolean	No	Require click to reveal content. Default: true
allowDeletion	boolean	No	Allow recipient to delete after viewing. Default: true

Error Handling

All error responses follow a consistent format with an error code and helpful hint:

JSON

{
  "error": "Invalid passphrase",
  "code": "INVALID_PASSPHRASE",
  "hint": "The secret is password-protected. Include the correct 'passphrase' in your request body.",
  "requestId": "req_m4kbz6_mno345"
}

HTTP Status Codes

Status	Meaning	Description
200	OK	Request succeeded
400	Bad Request	Invalid or missing parameters
401	Unauthorized	Invalid passphrase for protected secret
404	Not Found	Secret not found, expired, or already viewed
410	Gone	Secret burned, expired, or max views reached
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error

Error Codes

Code	Description
INVALID_KEY	Key format is invalid (must be alphanumeric)
INVALID_JSON	Request body is not valid JSON
MISSING_SECRET	No secret content provided in request
CONTENT_TOO_LARGE	Secret exceeds size limit for your tier
NOT_FOUND	Secret doesn't exist or has been deleted
INVALID_PASSPHRASE	Wrong passphrase for protected secret
SECRET_BURNED	Secret was manually deleted by sender
SECRET_EXPIRED	Secret has passed its expiration time
MAX_VIEWS_REACHED	Secret has reached maximum view count
RATE_LIMIT_EXCEEDED	Too many requests, check Retry-After header
INTERNAL_ERROR	Server error, contact support if persistent

Rate Limits

API requests are rate-limited based on your authentication level. Limits reset on a sliding window.

Resource	Anonymous	Authenticated	API Key
Requests per hour	10	100	1,000
Requests per day	50	1,000	Unlimited
Max secret size	1 MB	50 MB	50 MB
Max TTL	7 days	999 days	999 days
Max view limit	10	999	999

Rate Limit Headers

All API responses include rate limit headers:

X-RateLimit-Limit — Maximum requests allowed
X-RateLimit-Remaining — Requests remaining in current window
X-RateLimit-Reset — Unix timestamp when the limit resets
X-Request-Id — Unique request identifier for debugging

When rate limited, responses include a Retry-After header with seconds until reset.

Ready to get started?

Create your API key and start integrating Burn the Secret into your applications.

Get API Key