CHANGE
LOG.

Remote MCP endpoint at https://hollywoodmetrics.ai/mcp (streamable HTTP, stateless JSON mode). Seventeen tools cover the film catalog, screenplay tier analysis, outcome forecasting, craft style guides, and the Studio-tier AI services. Authenticate with your existing API key as an Authorization: Bearer header, or connect keyless for read-only sandbox access at 25 requests per day per IP.

Tool calls meter exactly like REST calls: one tool call is one request against your daily limit, with the same scopes and tier gates. The get_account_status tool is free and reports remaining quota.

POST /api/v1/scripts/analyze now returns correct results. It shares the dashboard's canonical feature extractor (name-keyed, with real sentiment), so the 20 measured features, tier prediction, and z-scores line up with the model instead of a misaligned vector. GET /api/v1/scripts and /api/v1/scripts/{id} now return the full measured-feature dict for each screenplay rather than an empty object.

Live playground at /api-docs#playground. Five presets (film detail, search, genre-filter, decade slice, catalog snapshot) fire real requests against /api/v2 from the browser, with a sandbox key included for the unauthenticated demo.

Curated endpoint reference with sidebar nav, parameter tables, and tabbed curl / node / python samples per endpoint.

Auth section now includes the canonical error envelope shape and the full error code table — every 4xx and 5xx the v2 surface returns.

GET /api/v2/catalog/snapshot returns a 302 to a signed Cloud Storage URL for a gzipped NDJSON dump of the entire catalog. One row per canonical Film object. Suitable for one-shot ingestion into a local index or vector store.

Pass format=json to get the manifest and signed URL inline without following the redirect. Useful for clients that can't stream-download in a single request.

curl -H "X-API-Key: hm_..." \
  "https://hollywoodmetrics.ai/api/v2/catalog/snapshot?format=json"

Bucket has public-access-prevention enabled — the signed URL is the only reach into the snapshot file. Default expiry is one hour, which is enough for any reasonable ingestion path.

POST /api/v2/recommend response shape changed. Picks are now { film: Film, reason: string } rather than the legacy v1 compact shape with embedded score. v1 /recommend stays online unchanged.

{
  "data": [
    { "film": { "imdb_id": "tt0073195", ... }, "reason": "..." },
    ...
  ]
}

Per-pick reasons are now short editorial strings (one sentence) rather than a raw similarity score. Clients can still derive ranking from the array order.

Optional filters object accepted on the POST body — pre-filter by genre / decade / min_rating before the recommender runs.

GET /api/v2/films/stream — newline-delimited JSON, one canonical Film per line, the entire catalog in a single response. Counts as one request against your daily budget.

fields= query parameter on /films and /films/stream. Comma-separated field projection trims the response to just the columns you ask for. Smaller lines, faster ingestion.

curl -H "X-API-Key: hm_..." \
  "https://hollywoodmetrics.ai/api/v2/films?fields=imdb_id,title,year,master_score&limit=50"

Cursor pagination on /films now returns a stable next_cursor token in the meta envelope. Decoding stays opaque — don't reverse-engineer the offset, just pass the token through.

All Film objects now carry poster_full_url and poster_mini_url pointing at our Cloud Storage bucket. The TMDB CDN remains the fallback when the bucket entry is missing.

Cache-Control: public, max-age=300, stale-while-revalidate=3600 applied to every v2 GET. Edge caching is now configured to honor it.

Master score field (master_score) is now consistently present on the canonical Film. Previous releases occasionally omitted it on films that lacked one or more component metrics.

v2 base path is /api/v2. v1 stays online at /api/v1 for existing integrations but new builds should target v2. See the migration callout above for the field-by-field rename map.

Canonical Film object across every endpoint: top cast (with characters), crew grouped by department, GCS poster URLs at full and mini resolution, watch providers, external IDs, and self/similar/poster-analysis hypermedia links.

Catalog expanded to the full TMDB-enriched set. 74,571 films, 107 years of cinema, 37,993 with posters in the bucket.

Cursor pagination on list endpoints. Pass meta.next_cursor on the next request to walk the catalog without juggling offsets.

Metric provenance schema on every numeric field. Each Metric carries metric_type, market, period, and source — so a downstream client always knows where a number came from.

OpenAPI 3.0 spec bumped to 2.0.0 at /openapi.json with CanonicalFilm, CanonicalCastMember, CanonicalCrewMember, PosterAnalysis, and V2PaginationMeta schema components.

v1 list response shape is now considered legacy. v1 continues to work for at least 12 months. The cutoff date and migration deadline will be announced here at least 90 days in advance.

Self-service API key creation via POST /api/v1/keys/self-generate. Producer and Studio tiers only. Free and Writer tiers continue to use the in-app key inspector on /dashboard.

TypeScript and Python SDKs available at /sdk/. Both wrap the X-API-Key header, surface canonical error envelopes, and ship TypeScript types for the v1 response shapes.

Sandbox mode via X-Sandbox header or hm_sandbox_ key prefix. Requests against the sandbox don't consume daily quota and return the same shape with a sandbox=true flag in the meta envelope.

Rate-limit response headers now include X-RateLimit-Warning at 80%+ daily usage. Clients can surface an in-app warning before the 429 wall.

Seven AI endpoints for screenplay work: compare-style, style-match, trailer-concept, logline, visual-treatment, cast-recommend, and a deep analyzer. All gated to Studio tier because the per-call cost is real.

Annual billing on every paid tier. Two months free if you commit annually. Stripe checkout now supports promo codes.

Search endpoint now supports offset pagination on the v1 surface. Cursor pagination arrived later in v2.

Rate limiting moved to in-memory with write-behind to Firestore. Roughly 10x faster on hot paths; worst-case over-count is bounded by instance count.

POST /api/v1/posters/analyze runs a Studio-tier vision pass on a poster and returns mood, palette, composition, era, and a short editorial note. Stored back on the Film object for subsequent reads.

GET /api/v1/posters/stats and /api/v1/posters/films expose the aggregate and per-film poster analysis data.

Decade filter on /films now correctly handles boundary years. 1990s now includes 1990 (was previously off-by-one).

GET /api/v1/styles/writers, /api/v1/styles/directors, and /api/v1/styles/cinematographers return the curated style guides as JSON, suitable for embedding in a writing tool.

Script analyzer (POST /api/v1/scripts/analyze) now returns the full 20-feature set per script alongside the tier prediction.

GET /api/v1/correlations exposes the 20-feature × 8-outcome correlation matrix that powers the analytics page.

GET /api/v1/model returns architecture, accuracy, and per-feature importances for the screenplay tier predictor.

Initial v1 REST surface with 21 endpoints across films, scripts, posters, styles, and AI analysis.

API key authentication with scoped permissions (read, write, ai, admin). Keys live on the dashboard under Account → API Keys.

Daily rate limits by subscription tier. Writer 10/day, Producer 200/day, Studio 10,000/day. Free tier is web-only.

OpenAPI 3.0 spec at /openapi.json. Generate clients from the spec or hand-write against the curated /api-docs reference.