API Documentation

The PoofKey API allows you to programmatically create and manage secure secrets. All endpoints use HTTPS and return JSON responses.

Premium Feature: API access requires a paid subscription and valid API key.

Getting Started

The PoofKey API allows you to programmatically create and manage secure secrets with enhanced features. All endpoints require authentication via API key.

Base URL

https://www.poofkey.com/api/

Authentication

All API requests require a valid API key in the X-API-Key header:

X-API-Key: your_api_key_here

Create Secret

POST /api/create

Request Body

{
  "secret": "Your sensitive data here",
  "title": "Optional title for the secret",
  "description": "Optional description",
  "max_views": 1,
  "expiration_hours": 24
}

Response

{
  "success": true,
  "secret_url": "https://www.poofkey.com/premium/secret/abc123...",
  "secret_id": "abc123...",
  "expires_at": "2025-01-15T10:30:00Z",
  "max_views": 1
}

Example

curl -X POST https://www.poofkey.com/api/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "secret": "My sensitive password",
    "title": "Database Password",
    "description": "Production database access",
    "max_views": 1,
    "expiration_hours": 24
  }'

List Secrets

GET /api/list

Response

{
  "success": true,
  "secrets": [
    {
      "id": "abc123...",
      "title": "Database Password",
      "description": "Production database access",
      "created_at": "2025-01-15T10:30:00Z",
      "expires_at": "2025-01-16T10:30:00Z",
      "max_views": 1,
      "current_views": 0,
      "is_expired": false,
      "can_be_viewed": true
    }
  ]
}

Example

curl -X GET https://www.poofkey.com/api/list \
  -H "X-API-Key: your_api_key_here"

Reveal Secret

POST /api/reveal/{secret_id}

Note: This endpoint reveals and consumes one view of the secret. The secret will be destroyed after reaching its maximum view limit.

Response

{
  "success": true,
  "secret": "Your revealed secret content",
  "views_remaining": 0
}

Error Response (Secret not found)

{
  "error": "Secret not found"
}

Error Response (Secret expired)

{
  "error": "Secret expired"
}

Error Response (View limit reached)

{
  "error": "Secret limit reached"
}

Example

curl -X POST https://www.poofkey.com/api/reveal/abc123... \
  -H "X-API-Key: your_api_key_here"

Delete Secret

DELETE /api/delete/{secret_id}

Response

{
  "success": true,
  "message": "Secret deleted successfully"
}

Example

curl -X DELETE https://www.poofkey.com/api/delete/abc123... \
  -H "X-API-Key: your_api_key_here"

Security

  • All data is encrypted using AES-256-GCM authenticated encryption
  • Zero-knowledge architecture
  • Automatic destruction after viewing or expiration
  • Configurable expiration times (1 hour to 30 days)
  • Multiple view limits (up to 100 views)
  • No logs or traces retained

Error Codes

400 Bad Request - Invalid or missing data
401 Unauthorized - Invalid or missing API key
403 Forbidden - Access denied
404 Not Found - Secret doesn't exist
410 Gone - Secret already viewed/expired
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error

Getting Your API Key

To access the API, you need a premium subscription and API key:

  1. Sign up for a premium account
  2. Log in to your dashboard
  3. Navigate to "API Key Management"
  4. Generate your API key
  5. Include the key in all API requests

Security Note: Keep your API key secure and never share it publicly. If compromised, regenerate it immediately.