# Documentation

Canonical URL: https://burnthesecret.com/docs
Markdown URL: https://burnthesecret.com/docs.md

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 90 days
-   **View limits** — Secrets auto-delete after a set number of views
-   **Password protection** — Optional passphrase for extra security
-   **File support** — Share files and text up to 2 MB combined
-   **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, access stops. Expired secrets and attachments are deleted from the active database by hourly cleanup, normally within one hour. New secrets last at most 90 days; existing secrets keep their saved expiry dates. Unlimited views never extend expiry.

## Authentication

Authentication is **optional**. You can create secrets without any API key—sending a key only links the secret to your account. To attribute a secret, include your key in the`Authorization`header:

HTTP Header

```
Authorization: Bearer ks_live_your_api_key
```

Get your API key from the [API Access](https://burnthesecret.com/api-docs) page in your dashboard. Omit the header and the request is still accepted (anonymous, or linked to your signed-in browser session). Only if you send a key that is invalid or revoked is the request rejected—with `401 INVALID_API_KEY`. 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,
    "hasText": true,
    "fileCount": 0,
    "maxViews": 1,
    "viewCount": 0,
    "serverEncrypted": true
  },
  "secretUrl": "https://burnthesecret.com/secret/def456uvw#key=Zm9vYmFy...",
  "metadataUrl": "https://burnthesecret.com/receipt/abc123xyz",
  "requestId": "req_m4k7x2_abc123"
}
```

### JavaScript

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

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,
  "text": {
    "ciphertext": "base64-encoded-ciphertext...",
    "iv": "base64-encoded-iv..."
  },
  "files": [],
  "oneClickRetrieval": true,
  "viewsRemaining": 0,
  "requestId": "req_m4k8y3_def456"
}
```

The API returns the encrypted `text` as `{ ciphertext, iv }`, never a decrypted plaintext value. Decrypt it client-side using the key from the URL fragment (the part after `#`).

## Delete Secret

Permanently delete (burn) a secret before it expires. You can burn with either the metadata key or the secret key. If the sender disabled deletion, burning with the secret key returns`403 DELETION_NOT_ALLOWED`.

`DELETE /api/secrets/:key`

### 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 2 MB) |
| ttl | integer | No | Time to live in whole seconds. Min: 1800 (30 min), Max: 7776000 (90 days). Default: 86400 (1 day) |
| maxViews | integer \| null | No | Max views before deletion. 1-999, or null for unlimited views until expiry. Default: 1 |
| passphrase | string | No | Raw passphrase, 4-256 chars (sent over HTTPS; hashed server-side). If set, 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 | API key sent but invalid or revoked (a key is optional) |
| 403 | Forbidden | Invalid passphrase, or burn blocked because the sender disabled deletion |
| 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 |
| INVALID\_API\_KEY | API key was sent but is invalid or revoked (a key is optional) |
| MISSING\_CONTENT | No secret content (text, secret, or files) provided in request |
| CONTENT\_TOO\_LARGE | Secret exceeds the 2 MB content limit |
| 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 per IP address on a sliding window. The limits below apply uniformly to every request—anonymous, signed in, or using an API key. There are no per-tier limits.

| Resource | Limit |
| --- | --- |
| Max content size | 2 MB combined content |
| Max TTL | 90 days |
| Max view limit | 999 (or unlimited with null) |
| Max files per secret | 20 |

### 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](https://burnthesecret.com/api-docs)