Skip to content
v1 — LIVE

REST API Documentation

Pull greenlight.film project data into your own platform. 19 endpoints. Bearer token auth. JSON responses. CORS enabled.

Quick Start

1. Get an API key from the admin panel (or contact hello@greenlight.film)
2. Make your first request:
curl -H "Authorization: Bearer gl_pk_your_key_here" \
  https://your-deployment.convex.cloud/api/v1/projects?limit=5
Response:
{
  "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-Id

API Tiers

Free
$0
10 req/hr
Starter
$99/mo
100 req/hr
Growth
$299/mo
1,000 req/hr
Enterprise
Custom
10,000 req/hr

API tiers are separate from consumer subscriptions (Reader/Professional/Producer).

Endpoints

MethodPathDescription
GET/api/v1/healthHealth check
GET/api/v1/projectsList projects with filters, sorting, pagination
GET/api/v1/project-detailSingle project by ?number=N
GET/api/v1/project-batchBatch lookup by ?numbers=1,2,3 (max 50)
GET/api/v1/project-packageFull project: metadata + deliverables + reviews + assets
GET/api/v1/deliverablesProject deliverables by ?number=N&type=screenplay
GET/api/v1/reviewsSimulated critic reviews by ?number=N
GET/api/v1/assetsAsset URLs (poster, covers, boards) by ?number=N
GET/api/v1/searchFull-text search by ?q=term&limit=20&offset=0
GET/api/v1/statsCatalog statistics
GET/api/v1/enumsValid filter values (genres, mediums, styles, ratings, etc.)
GET/api/v1/featuredTop-ranked projects
GET/api/v1/catalogBulk JSON export (counts as 10 requests)
GET/api/v1/blogPublished blog posts with ?tag=&limit=&offset=
GET/api/v1/blog-postSingle blog post by ?slug=
POST/api/v1/webhooksRegister outbound webhook
GET/api/v1/webhooksList registered webhooks
POST/api/v1/webhook-testSend test ping to a webhook
POST/api/v1/webhook-deleteDelete a webhook by ?id=X

Filtering & Sorting (/projects)

ParameterExampleDescription
genrehorrorFilter by genre
mediumlive-actionFilter by medium
styledarkFilter by visual style
ratingRFilter by content rating
formatfilmFilter by format (film, tv, etc.)
option_statusavailableFilter by availability (available, optioned, sold)
created_after2026-03-01Projects added after date (ISO 8601)
sortcommercial_rankSort by: number, title, commercial_rank, artistic_rank, tv_series_rank
limit25Page size (max 100)
offset0Pagination 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_sold

Each 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.

Errors

{
  "error": { "code": "rate_limit_exceeded", "message": "...", "details": { "retry_after": 3600 } },
  "meta": { "api_version": "v1", "request_id": "uuid", "timestamp": "ISO" }
}
400 Bad request401 Unauthorized403 Forbidden (tier/IP)404 Not found429 Rate limited500 Server error

Ready to integrate? Get an API key or contact us for enterprise pricing.

Request API KeyView Pricing