REST API Documentation
Pull greenlight.film project data into your own platform. 24 endpoints. Bearer token auth. JSON responses. CORS enabled.
Quick Start
curl -H "Authorization: Bearer gl_pk_your_key_here" \ https://your-deployment.convex.cloud/api/v1/projects?limit=5
{
"data": [ { "number": 1, "title": "...", "genre": "...", ... } ],
"meta": { "api_version": "v1", "request_id": "uuid", "timestamp": "ISO" },
"pagination": { "total": 308, "limit": 5, "offset": 0, "has_more": true }
}Authentication
Pass your API key as a Bearer token in the Authorization header:
Authorization: Bearer gl_pk_a1b2c3d4e5f6...
Keys are SHA-256 hashed at rest. The raw key is shown once on creation. Rate limit headers are included on every response:
X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-ResetX-Request-IdAPI Tiers
Free, Starter, and Growth plans are self-service. Studio plans include dedicated support, custom rate limits, and SLA guarantees — contact us to discuss.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/health | Health check |
| GET | /api/v1/projects | List projects with filters, sorting, pagination |
| GET | /api/v1/project-detail | Single project by ?number=N |
| GET | /api/v1/project-batch | Batch lookup by ?numbers=1,2,3 (max 50) |
| GET | /api/v1/project-package | Full project: metadata + deliverables + reviews + assets |
| GET | /api/v1/deliverables | Project deliverables by ?number=N&type=screenplay |
| GET | /api/v1/reviews | Simulated critic reviews by ?number=N |
| GET | /api/v1/assets | Asset URLs (poster, covers, boards) by ?number=N |
| GET | /api/v1/search | Full-text search by ?q=term&limit=20&offset=0 |
| GET | /api/v1/stats | Catalog statistics |
| GET | /api/v1/enums | Valid filter values (genres, mediums, styles, ratings, etc.) |
| GET | /api/v1/featured | Top-ranked projects |
| GET | /api/v1/catalog | Bulk JSON export (counts as 10 requests) |
| GET | /api/v1/blog | Published blog posts with ?tag=&limit=&offset= |
| GET | /api/v1/blog-post | Single blog post by ?slug= |
| POST | /api/v1/webhooks | Register outbound webhook |
| GET | /api/v1/webhooks | List registered webhooks |
| POST | /api/v1/webhook-test | Send test ping to a webhook |
| POST | /api/v1/webhook-delete | Delete a webhook by ?id=X |
| GET | /api/v1/my-purchases | List your purchased and optioned projects |
| GET | /api/v1/my-assets | Get download links for a purchased project by ?number=N |
| GET | /api/v1/download | Download a deliverable file (token-authenticated) |
| GET | /api/v1/download-package | Full download manifest with all file URLs by ?number=N |
| GET | /api/v1/verify-access | Check if you have access to a project by ?number=N |
Filtering & Sorting (/projects)
| Parameter | Example | Description |
|---|---|---|
| genre | horror | Filter by genre |
| medium | live-action | Filter by medium |
| style | dark | Filter by visual style |
| rating | R | Filter by content rating |
| format | film | Filter by format (film, tv, etc.) |
| option_status | available | Filter by availability (available, optioned, sold) |
| created_after | 2026-03-01 | Projects added after date (ISO 8601) |
| sort | commercial_rank | Sort by: number, title, commercial_rank, artistic_rank, tv_series_rank |
| limit | 25 | Page size (max 100) |
| offset | 0 | Pagination offset |
All filters stack with AND logic. Use /enums to discover valid values.
Webhooks
Subscribe to real-time events. Payloads are HMAC-SHA256 signed with your webhook secret.
new_projectproject_updatedproject_soldEach delivery includes X-Greenlight-Signature (HMAC), X-Greenlight-Event, and X-Greenlight-Event-Id (for dedup).
Circuit breaker: webhooks auto-pause after 5 consecutive delivery failures. Max 10 webhooks per key.
Test your endpoint with POST /api/v1/webhook-test?id=... before going live.
Asset Delivery
Download deliverables and images for projects you have purchased or optioned.
1. Check access: GET /api/v1/verify-access?number=196 confirms ownership.
2. List purchases: GET /api/v1/my-purchases returns all your purchased and optioned projects.
3. Get asset links: GET /api/v1/my-assets?number=196 returns download URLs for all deliverables and images.
4. Download files: GET /api/v1/download?token=...&type=screenplay downloads a specific deliverable. No API key header needed — the token is the auth.
5. Bulk download: GET /api/v1/download-package?number=196 (Growth+) returns a manifest of all files with download URLs.
Download Token Security
Download tokens expire after 1 hour and are single-use.
Tokens are bound to the API key that generated them. Every download is logged.
Request new tokens by calling /my-assets or /download-package again.
Errors
{
"error": { "code": "rate_limit_exceeded", "message": "...", "details": { "retry_after": 3600 } },
"meta": { "api_version": "v1", "request_id": "uuid", "timestamp": "ISO" }
}Ready to integrate? Create a free account and generate your API key instantly.