canonical: https://jentic.com/apis/festivalapi.com/festivalapi # Festival API The Festival API aggregates film-festival data into a single JSON surface: submission deadlines, categories and genres, standard submission fees, submission platforms, past winners, programming rosters, and a composite score. It lists and filters festivals, returns the full detail for one festival including its roster and programming profile, and ranks the top-scored festivals. Supporting endpoints expose categories, countries, states, a calendar feed, and the deadlines closing soon. Authentication uses a bearer API key. ## For AI agents Search and discover film festivals through the Festival API: list and filter festivals, read a festival's detail, roster, and programming profile, rank the top-scored festivals, and check deadlines closing soon. ## Scope Does not handle submitting films, processing submission payments, or managing a festival's back office. Use for reading and discovering film-festival data such as deadlines, fees, rosters, and scores only. ## Capabilities - List and filter film festivals via GET /festivals/ - Read a single festival's full detail, including fees, deadlines, and platforms, via GET `/festivals/{id}`/ - Read a festival's programming roster and programming profile via GET `/festivals/{id}/roster`/ and GET `/festivals/{id}/programming-profile`/ - Rank the top composite-scored festivals via GET `/festivals/scored`/ - Find deadlines closing soon via GET `/deadlines/closing-soon`/ - Browse categories, countries, and states via GET /categories/, GET /countries/, and GET /states/ - Pull a festival calendar feed via GET /calendar/ ## Use cases ### AI agent festival recommender An AI assistant helps a filmmaker decide where to submit by pulling live festival data on demand. Through Jentic it filters festivals, reads their deadlines and fees, and ranks the top-scored options, then returns a shortlist with the next deadlines. Jentic injects the Festival API key at call time, so the agent never holds the credential. Example prompt: Search Jentic for 'find film festivals to submit to', call GET /festivals/ with filters, read GET `/festivals/scored`/ for ranking, and summarise the shortlist with each festival's next deadline ### Submission deadline tracking Filmmakers miss festivals because deadlines creep up across dozens of events. The Festival API surfaces the deadlines closing soon and the fee tiers behind each one, so a tracker can remind a user before a window closes. Reading one festival's detail returns its full deadline and platform information. Example prompt: Call GET `/deadlines/closing-soon`/ to find imminent deadlines, then read GET `/festivals/{id}`/ for each to confirm its fee tiers and submission platforms ### Festival discovery and filtering A discovery experience lets users browse festivals by category, country, and state and drill into any one. The Festival API exposes the category, country, and state reference lists alongside a filterable festival list, so a frontend can build facet filters that map to real data. Each festival detail includes the roster and programming profile for deeper context. Example prompt: Call GET /categories/, GET /countries/, and GET /states/ to build filters, then call GET /festivals/ with the chosen facets to list matching festivals ### Score-based festival shortlist When there are too many festivals to weigh by hand, a composite score helps rank them. The Festival API returns the top-scored festivals directly, so an agent can build a shortlist ordered by that score and then pull each festival's roster and programming profile to judge fit. This turns a sprawling list into a ranked, explainable set. Example prompt: Call GET `/festivals/scored`/ for the ranked list, then read GET `/festivals/{id}/programming-profile`/ for the top entries to judge programming fit ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/festivals/` | List festivals | | GET | `/festivals/{id}/` | Get festival detail | | GET | `/festivals/{id}/roster/` | Get festival roster | | GET | `/festivals/scored/` | Get top-scored festivals | | GET | `/deadlines/closing-soon/` | Get deadlines closing soon | | GET | `/festivals/{id}/programming-profile/` | Get a festival's programming profile | | GET | `/calendar/` | Get the festival calendar feed | | GET | `/categories/` | List categories | ## Key resources - **Festivals** — List and filter festivals and read one festival's detail, roster, and programming profile - **Scored festivals** — Rank festivals by a composite score - **Deadlines and calendar** — Find deadlines closing soon and pull a festival calendar feed - **Reference lists** — Browse categories, countries, and states used to filter festivals ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 62 / 100 - **Maturity:** AI-Aware - **Dimensions:** - Foundational Compliance: 71 / 100 - Developer Experience & Jentic Compatibility: 56 / 100 - AI-Readiness & Agent Experience: 45 / 100 - Agent Usability: 94 / 100 - Security: 60 / 100 - AI Discoverability: 82 / 100 - **View full report:** https://jentic.com/apis/festivalapi.com/festivalapi/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring the Festival API by hand means managing its bearer key, remembering the trailing-slash paths, and stitching the reference lists into festival filters yourself. Through Jentic you install once, import the Festival API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** The Festival API is read-only, so a rule can allow your agent just the lookups it needs: the festival list, a festival read by the id in its path, or the scored and deadline feeds. You choose the operations it may call, and because nothing writes, the agent can only read festival data. - **Credential handling:** Your Festival API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'find film festivals to submit to' or 'festival deadlines closing soon', and Jentic returns the matching Festival API operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **TMDB API** — Broad film and TV metadata source, a different slice of film data than festival submissions - **OMDb** — Movie and series metadata lookup to enrich a festival's programming titles - **Watchmode API** — Streaming availability data for titles discovered through festival programming ## FAQ ### What authentication does the Festival API use? The Festival API authenticates with a bearer API key issued from your Festival API dashboard, sent as a Bearer token, per its OpenAPI spec. When you call it through Jentic, the key is stored encrypted by your own Jentic One instance and injected at execution time, so it never enters the agent's prompt, logs, or context. ### Can I filter festivals by category or country with the Festival API? Yes. Build your facets from GET /categories/, GET /countries/, and GET /states/, then call GET /festivals/ with the chosen filters to list matching festivals. Each festival's full detail, including fees and deadlines, comes back from GET `/festivals/{id}/.` ### Can the Festival API tell me which deadlines are closing soon? Yes. Call GET `/deadlines/closing-soon`/ for the festivals whose submission windows are near, and read GET `/festivals/{id}`/ for each one to see its full deadline and fee information. A calendar feed is also available from GET `/calendar/.` ### What are the rate limits for the Festival API? The OpenAPI spec does not specify rate limits for the Festival API. Check the Festival API documentation for current limits, cache reference lists like categories and countries, and have your agent back off when the API signals that it is being throttled. ### How do I find festivals to submit to through Jentic? Search Jentic for 'find film festivals to submit to' to load the Festival API operations with their input schemas, call GET /festivals/ with your filters, and rank results with GET `/festivals/scored/.` To run it on your own infrastructure, install Jentic One from its GitHub repo. ### Can I limit what my agent is allowed to do with the Festival API? Yes. The Festival API is read-only, so a rule can allow your agent just the lookups it needs, such as listing festivals, reading one by the id in its path, or the scored and deadline feeds. Because nothing writes, the agent can only read festival data, and every call it makes is logged.