API Reference - DVD Database Server

Base URL

https://api.dvddb.org/

All API requests should be made to this base URL using HTTPS.

🔐 Authentication

Most API endpoints require Bearer token authentication. Include your token in the Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

Generating Tokens

Tokens are generated on the server using the provided script:

export DVDDB_PG_PASSWORD='your_password'
cd /opt/dvddb-api
./scripts/generate_token.sh "Token Name" "Description" 5000 10

# Arguments:
#   "Token Name"   - Friendly identifier
#   "Description"  - Purpose/owner notes
#   5000           - Max points (bucket size)
#   10             - Regen rate (points/minute)

Security Notes

Tokens are hashed with SHA256 before storage (never stored in plaintext)
Keep your tokens secure - they provide full API access
Rotate tokens regularly
Use different tokens for different applications

📍 API Endpoints

GET /health

No Auth Required

Health check endpoint for monitoring.

Example Request:

curl https://api.dvddb.org/health

Example Response:

{
  "status": "ok",
  "timestamp": "2026-02-08T12:34:56Z",
  "database": "connected"
}

GET /api/v1/lookup/:sha1

Auth Required

Lookup content by SHA1 hash.

Path Parameters:

Parameter	Type	Description
sha1	string	40-character SHA1 hash (lowercase hexadecimal)

Query Parameters:

Parameter	Type	Default	Description
type	enum	exists	Response type: exists, skel, or full

Point Costs:

Type	Points	Description
exists	1	Boolean check - does this SHA1 exist?
skel	10	Basic metadata (title, year, type)
full	50	Complete data with genres, cast, crew, and relationships

Example Request (exists):

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.dvddb.org/api/v1/lookup/abc123...?type=exists"

Example Response (exists):

{
  "exists": true
}

Example Response (skel):

{
  "exists": true,
  "content": {
    "content_id": 1,
    "primary_title": "The Matrix",
    "release_year": 1999,
    "content_type": "movie",
    "runtime_minutes": 136
  }
}

Example Response (full):

{
  "exists": true,
  "content": {
    "content_id": 1,
    "primary_title": "The Matrix",
    "release_year": 1999,
    "content_type": "movie",
    "runtime_minutes": 136,
    "synopsis": "A computer hacker learns...",
    "genres": ["Science Fiction", "Action"],
    "cast": [...],
    "crew": [...],
    "discs": [...]
  }
}

Response Headers:

All authenticated responses include point tracking headers:

Header	Description
X-Points-Remaining	Current points after this request
X-Points-Max	Maximum point capacity
X-Points-Regen-Rate	Points regenerated per minute
X-Points-Cost	Points deducted for this request

Example with Headers:

curl -i -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.dvddb.org/api/v1/lookup/abc123...?type=full"

HTTP/1.1 200 OK
X-Points-Remaining: 4950
X-Points-Max: 5000
X-Points-Regen-Rate: 10
X-Points-Cost: 50
Content-Type: application/json

{"exists": true, "content": {...}}

⚖️ Point System

The API uses a token bucket algorithm for fair resource allocation and throttling.

How It Works

Each token starts with max_points capacity
Each request costs points based on type (exists=1, skel=10, full=50)
Points regenerate at regen_rate_per_minute
Points cannot exceed max_points (bucket capacity)
Requests fail with HTTP 429 when insufficient points

Token Configuration

Setting	Description	Typical Value
max_points	Maximum point capacity (bucket size)	5000
regen_rate_per_minute	Points regenerated per minute	10

Example Calculations

# Starting with 5000 points, regen rate 10/min

# After 50 full lookups (50 × 50 = 2500 points):
Remaining: 2500 points
Can make: 2500 exists OR 250 skel OR 50 full
Fully recharges in: 250 minutes (4h 10m)

# After 500 exists lookups (500 × 1 = 500 points):
Remaining: 4500 points
Can make: 4500 exists OR 450 skel OR 90 full
Fully recharges in: 50 minutes

# Steady state (sustained usage):
At 10 points/min regen, sustained throughput:
  - 10 exists/min OR
  - 1 skel/min OR
  - 1 full every 5 minutes

Best Practices

Use exists first: Check if content exists (1pt) before fetching full data (50pts)
Cache responses: Store full responses locally to avoid repeated lookups
Use skel when possible: If you don't need full cast/crew, use skel (10pts vs 50pts)
Monitor headers: Watch X-Points-Remaining to avoid hitting limits
Implement backoff: When approaching 0 points, slow down requests

⚠️ Error Responses

401 Unauthorized

Invalid or missing authentication token.

{
  "error": "Invalid or missing authentication token"
}

429 Too Many Requests

Insufficient points to complete the request.

{
  "error": "Insufficient points",
  "points_required": 50,
  "points_available": 25,
  "retry_after_seconds": 150
}

Wait for points to regenerate or reduce request frequency.

404 Not Found

Content not found for the given SHA1 hash.

{
  "exists": false
}

400 Bad Request

Invalid request parameters (e.g., malformed SHA1, invalid type).

{
  "error": "Invalid SHA1 format"
}

500 Internal Server Error

Server-side error. Contact support if persistent.

{
  "error": "Internal server error"
}

📊 Rate Limiting

In addition to the point system, the following limits apply:

Connection limit: 100 concurrent connections per token
Request timeout: 30 seconds
Keep-alive timeout: 15 seconds
Nginx rate limit: 100 req/sec per IP (backup protection)