v1 — LIVE

REST API Documentation

Pull greenlight.film project, book, and audiobook data into your own platform. 38 endpoints. Bearer token auth. JSON responses. CORS enabled. Plus a remote MCP server with casting-registry tools.

Quick Start

Base URLhttps://www.greenlight.film/api/v1

1. Sign in and generate an API key from your API keys page

2. Make your first request:

curl -H "Authorization: Bearer gl_pk_your_key_here" \
  "https://www.greenlight.film/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 }
}

Connect via MCP

The Greenlight MCP server connects AI assistants directly to all three Greenlight catalogues — film development packages, published books, and audiobooks. It speaks MCP Streamable HTTP with stateless JSON, exposes 22 tools, and is hosted remotely, so there is nothing to install:

https://www.greenlight.film/api/mcp

Tools are tier-gated: Free (10 req/hr), Starter (100 req/hr), Growth (1,000 req/hr), Enterprise (10,000 req/hr) — see pricing. MCP requests are metered against the same hourly rate limit as the REST endpoints.

Claude CodeOAuth

One command in your terminal; Claude Code walks you through the OAuth sign-in on first use:

claude mcp add --transport http greenlight https://www.greenlight.film/api/mcp

claude.ai / Claude DesktopOAuth

Settings → Connectors → Add custom connector → paste the server URL. Sign in with your Greenlight account when prompted and click Approve.

https://www.greenlight.film/api/mcp

ChatGPTOAuth

Settings → Connectors → enable Developer mode → Create → paste the server URL with authentication set to OAuth. Sign in when prompted. Works with deep research — see the note below.

https://www.greenlight.film/api/mcp

VS Code / CursorAPI key

Add an HTTP MCP server pointing at the endpoint. In Cursor, add this to .cursor/mcp.json:

{
  "mcpServers": {
    "greenlight": {
      "url": "https://www.greenlight.film/api/mcp",
      "headers": { "Authorization": "Bearer gl_pk_your_key_here" }
    }
  }
}

OAuth (Claude, ChatGPT)

Hosts discover the server via /.well-known/oauth-protected-resource and run OAuth 2.1 with PKCE. Sign in with your Greenlight account and click Approve — no key handling, and your access tier follows your account's plan.

API key (Cursor, SDKs)

Generate a gl_pk_... key from your dashboard and send it as a Bearer token: "headers": {"Authorization": "Bearer gl_pk_..."} in Cursor's mcp.json, or as authorization_token in the Claude API / OpenAI Responses API MCP config.

ChatGPT deep research

The search and fetch tools follow the OpenAI connector contract: search returns ids like project:204, book:{slug}, and audiobook:{slug}, and fetch resolves them to full documents. Results cite canonical URLs on greenlight.film, greenlight-publishing.com, and greenlight-audio.com, so deep-research reports link straight back to the catalogue.

Film projects

get_license_status	Free	Tier, rate limit usage, catalogue versions (unmetered)
list_projects	Free	Browse the film catalogue with filters and sorting
search_projects	Free	Search projects by title keyword
get_project	Free	Full metadata for a single project
get_reviews	Starter	Critic reviews for a project
get_assets	Starter	All image/video URLs for a project
get_deliverable	Growth	One deliverable's full text (screenplay, treatment, ...)
get_project_package	Growth	Complete project with all deliverables

Books

list_books	Free	Browse the published novels
get_book	Free	Book detail, author bio, chapter list, store links
get_book_chapter	Free / Growth	Chapter text — free-preview chapters at any tier
export_book	Growth	Full book with all chapter content (billed as 5 requests)

Audiobooks

list_audiobooks	Free	Browse audiobooks by language and genre
get_audiobook	Starter	Audiobook detail with chapter durations
get_audiobook_chapter_audio	Growth	Streamable audio URL for one chapter

Casting

list_characters	Starter	Castable roles parsed from a project's Character Bible — name, age, role, design summary, voice, arc
search_actors	Starter	Browse/search the casting registry: human and synthetic performer profiles
get_actor	Starter	One performer profile by slug, incl. synthetic-performer provenance
submit_actor	Growth	Casting partners add/update performer profiles (write; attributed to your key)

Cross-catalogue

get_catalog_stats	Free	Aggregate statistics across projects and book genres
search	Free	Unified search across all three catalogues (ChatGPT deep-research contract)
fetch	Varies	Fetch a search result by id — project:241, book:slug, audiobook:slug

Search covers titles (projects) and title/description/genre (books, audiobooks) — not full text. A local stdio package (@greenlight/mcp-server) remains available for legacy setups.

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

Included with Free account

10 req/hr

Get Started

Starter

Included with Reader & Writer plans

100 req/hr

Growth

Included with Producer plan

1,000 req/hr

Enterprise

Included with Buyer plan / custom

10,000 req/hr

Let's Talk

Free, Starter, and Growth tiers are self-service — your API tier follows your subscription plan. Enterprise includes dedicated support, custom rate limits, and SLA guarantees — contact us to discuss.

Endpoints

Method	Path	Tier	Description
GET	/api/v1/health	None	Health check
GET	/api/v1/projects	Free	List projects with filters, sorting, pagination
GET	/api/v1/project-detail	Free	Single project by ?number=N
GET	/api/v1/project-batch	Starter	Batch lookup by ?numbers=1,2,3 (max 50)
GET	/api/v1/project-package	Growth	Full project: metadata + deliverables + reviews + assets
GET	/api/v1/deliverables	Growth	Project deliverables by ?number=N&type=screenplay
GET	/api/v1/reviews	Starter	Simulated critic reviews by ?number=N
GET	/api/v1/assets	Starter	Asset URLs (poster, covers, boards) by ?number=N
GET	/api/v1/search	Free	Full-text search by ?q=term&limit=20&offset=0
GET	/api/v1/stats	Free	Catalog statistics
GET	/api/v1/enums	Free	Valid filter values (genres, mediums, styles, ratings, etc.)
GET	/api/v1/featured	Free	Top-ranked projects
GET	/api/v1/catalog	Growth	Bulk JSON export (counts as 10 requests)
GET	/api/v1/blog	Free	Published blog posts with ?tag=&limit=&offset=
GET	/api/v1/blog-post	Free	Single blog post by ?slug=
POST	/api/v1/webhooks	Growth	Register outbound webhook
GET	/api/v1/webhooks	Growth	List registered webhooks
POST	/api/v1/webhook-test	Growth	Send test ping to a webhook
POST	/api/v1/webhook-delete	Growth	Delete a webhook by ?id=X
GET	/api/v1/my-purchases	Starter	List your purchased and optioned projects
GET	/api/v1/my-assets	Starter	Get download links for a purchased project by ?number=N
GET	/api/v1/download	None	Download a deliverable file (token-authenticated)
GET	/api/v1/download-package	Growth	Full download manifest with all file URLs by ?number=N
GET	/api/v1/verify-access	Free	Check if you have access to a project by ?number=N
GET	/api/v1/books	Free	List books by ?genre=&author=
GET	/api/v1/book-detail	Free	Book card + excerpt + chapter list by ?slug=
GET	/api/v1/book-chapter	Free	Chapter text by ?slug=&number= (free-preview chapters; others need Growth)
GET	/api/v1/book-package	Growth	Full book with all chapter content by ?slug= (counts as 5 requests)
GET	/api/v1/book-genres	Free	Book genres with counts
GET	/api/v1/audiobooks	Free	List audiobooks by ?language=&genre=
GET	/api/v1/audiobook-detail	Starter	Audiobook card + chapter durations by ?slug=
GET	/api/v1/audiobook-chapter	Growth	Chapter audio URL by ?slug=&number=
GET	/api/v1/characters	Starter	Castable roles parsed from a project's Character Bible by ?number=N
GET	/api/v1/actors	Starter	Casting registry: human + synthetic performers by ?kind=&q=
GET	/api/v1/actor-detail	Starter	One performer profile by ?slug=
POST	/api/v1/actor-submit	Growth	Casting partners add/update performer profiles (JSON body)
GET	/api/v1/search-all	Free	Unified search across projects, books, audiobooks by ?q=&types=
GET	/api/v1/license-status	Free	Your tier, rate-limit usage, catalog versions (unmetered)

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

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" }
}

400 Bad request401 Unauthorized403 Forbidden (tier/IP)404 Not found429 Rate limited500 Server error

Ready to integrate? Create a free account and generate your API key instantly.

Get API Key Enterprise → Let's Talk