Raven Zero - API Specification

📡 API Overview

Content Type: application/json (except file uploads)
Authentication: None (anonymous service)
Rate Limiting: Yes (per IP)
API Documentation: /scalar (interactive), /docs (Swagger), /redoc (ReDoc)

🔗 Endpoints Summary

📤 POST /upload/

Upload a file with auto-destruction parameters.

Request

Content-Type: multipart/form-data

Response

Status Code: 201 Created

{
  "key": "correct-horse-battery",
  "preview_url": "https://domain.com/preview/correct-horse-battery",
  "download_url": "https://domain.com/download/correct-horse-battery",
  "expiry": "2024-12-10T16:00:00Z",
  "uses": 3,
  "filename": "document.pdf",
  "size": 51200,
  "created_at": "2024-12-10T15:50:00Z",
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Examples

cURL:

curl -X POST https://domain.com/upload/ \
  -F "[email protected]" \
  -F "expiry=10" \
  -F "uses=3"

Python (httpx):

import httpx

files = {"file": ("document.pdf", open("document.pdf", "rb"), "application/pdf")}
data = {"expiry": 10, "uses": 3}

response = httpx.post("https://domain.com/upload/", files=files, data=data)
print(response.json())

Error Responses

👁️ GET /preview/{key}

Preview upload details. Can only be accessed once for security.

Request

Response

Status Code: 200 OK

{
  "key": "correct-horse-battery",
  "filename": "document.pdf",
  "size": 51200,
  "mime_type": "application/pdf",
  "expiry": "2024-12-10T16:00:00Z",
  "uses": 3,
  "minutes_left": 8,
  "download_url": "https://domain.com/download/correct-horse-battery",
  "curl_example": "curl -O https://domain.com/download/correct-horse-battery",
  "created_at": "2024-12-10T15:50:00Z",
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Error Responses

📥 GET /download/{key}

Download the file. Decrements remaining uses and verifies integrity.

Request

Response

Status Code: 200 OK

Headers:

Content-Disposition: attachment; filename="document.pdf"
Content-Type: application/pdf
X-SHA256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Body: Decrypted file binary content

Examples

cURL (save to file):

curl -O https://domain.com/download/correct-horse-battery

wget:

wget https://domain.com/download/correct-horse-battery

Behavior

1. First download: Uses decremented 3 → 2
2. Second download: Uses decremented 2 → 1
3. Third download: Uses decremented 1 → 0 → File auto-deletes
4. Fourth attempt: Returns 404

Error Responses

📊 GET /status/{key}

Check the status of an upload without consuming downloads.

Request

Response

Status Code: 200 OK

{
  "key": "correct-horse-battery",
  "status": "active",
  "remaining_uses": 2,
  "expires_at": "2024-12-10T16:00:00Z",
  "is_accessible": true
}

Possible Status Values:

• active — File is available for download
• expired — Time limit reached
• burned — Download limit reached
• expired_or_burned — File no longer exists

🏥 GET /health/

Health check endpoint for monitoring.

Response

Status Code: 200 OK

{
  "status": "healthy",
  "version": "0.1.0",
  "timestamp": "2024-12-10T15:50:00Z",
  "services": {
    "redis": "online",
    "storage": "online",
    "scheduler": "online",
    "diceware": "online"
  },
  "uptime_seconds": 3600,
  "started_at": "2024-12-10T14:50:00Z"
}

🔒 Security Headers

All responses include:

Cache-Control: no-store, no-cache, must-revalidate, max-age=0
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Referrer-Policy: no-referrer
X-Request-ID: {uuid}

🚦 Rate Limiting

Anti Brute-Force:

• 10 failed attempts → IP blocked for 30 minutes
• Applies to: /download, /preview, /status

🌐 CORS Policy

Allowed Origins: * (configurable)
Allowed Methods: GET, POST
Allowed Headers: Content-Type, Accept

📊 Error Response Format

Standard error:

{
  "detail": "Human-readable error message"
}

Validation error (Pydantic):

{
  "detail": [
    {
      "type": "error_type",
      "loc": ["body", "field_name"],
      "msg": "Error message"
    }
  ]
}

🔢 HTTP Status Codes

🔢 Data Types

Diceware Key Format

Pattern: word1-word2-word3
Example: correct-horse-battery

Rules:

• Exactly 3 words
• Lowercase letters only
• Separated by hyphens
• 7,776 word dictionary
• Combinations: 470,184,984,576 (~38.9 bits entropy)

Timestamp Format

Standard: ISO 8601 (UTC)
Format: YYYY-MM-DDTHH:MM:SSZ
Example: 2024-12-10T15:50:00Z

File Size

Format: Integer (bytes)
Maximum: 10,485,760 (10 MB)

🧪 Testing the API

Quick Test Flow

# 1. Upload a file
KEY=$(curl -s -X POST http://localhost:8000/upload/ \
  -F "[email protected]" \
  -F "expiry=10" \
  -F "uses=2" | jq -r '.key')

echo "Key: $KEY"

# 2. Preview (first time works)
curl http://localhost:8000/preview/$KEY | jq

# 3. Preview again (should fail - one-time only)
curl http://localhost:8000/preview/$KEY | jq

# 4. Check status
curl http://localhost:8000/status/$KEY | jq

# 5. Download (first time)
curl -O http://localhost:8000/download/$KEY

# 6. Download (second time, last use, file auto-deletes)
curl -O http://localhost:8000/download/$KEY

# 7. Download (should fail - no uses remaining)
curl http://localhost:8000/download/$KEY | jq

📚 Interactive Documentation

API Version: 0.1.0