API Documentation

Search and list film festivals. Returns up to 100 results. Filter by category using the category query parameter.

Query Parameters

Code Examples

curl -H "Authorization: Bearer *** \
     "https://festivalapi.com/v1/festivals?category=short_film"

import requests

headers = {"Authorization": "Bearer *** }
resp = requests.get(
    "https://festivalapi.com/v1/festivals",
    params={"category": "short_film"},
    headers=headers
)
data = resp.json()

const resp = await fetch(
  "https://festivalapi.com/v1/festivals?category=short_film",
  { headers: { "Authorization": "Bearer *** } }
);
const data = await resp.json();

require 'net/http'
require 'json'

uri = URI("https://festivalapi.com/v1/festivals?category=short_film")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer *** result = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
data = JSON.parse(result.body)

req, _ := http.NewRequest("GET", "https://festivalapi.com/v1/festivals?category=short_film", nil)
req.Header.Set("Authorization", "Bearer *** client := &http.Client{}
resp, _ := client.Do(req)

Example Response

{
  "count": 47,
  "results": [
    {
      "id": 1,
      "name": "Sundance Film Festival",
      "year": 2026,
      "country": "United States",
      "city": "Park City",
      "state": "Utah",
      "categories": ["feature", "short_film", "documentary"],
      "genres": ["drama", "comedy", "horror"],
      "deadline_regular": "2026-09-15",

      "event_start_date": "2027-01-21",
      "event_dates": "January 21-31, 2027",
      "regular_fee": 85,
      "submission_platforms": ["FilmFreeway"],
      "submission_url": "https://filmfreeway.com/Sundance",
      "website": "https://festival.sundance.org",
      "composite_score": 94.5
    }
  ]
}

Retrieve full details for a single film festival by ID. Includes submission info, categories, the primary deadline, standard fee, and festival details.

Path Parameters

Code Examples

curl -H "Authorization: Bearer *** \
     "https://festivalapi.com/v1/festivals/1/"

resp = requests.get(
    "https://festivalapi.com/v1/festivals/1/",
    headers={"Authorization": "Bearer *** }
)

const resp = await fetch(
  "https://festivalapi.com/v1/festivals/1/",
  { headers: { "Authorization": "Bearer *** } }
);

Returns films previously screened at this festival — titles, directors, years, and awards. Separate from the festival detail endpoint. Use this to research what a festival programs. Supports page/per_page pagination.

Query Parameters

Code Examples

curl -H "Authorization: Bearer *** \
     "https://festivalapi.com/v1/festivals/1/roster/"

resp = requests.get(
    "https://festivalapi.com/v1/festivals/1/roster/",
    headers={"Authorization": "Bearer *** }
)

const resp = await fetch(
  "https://festivalapi.com/v1/festivals/1/roster/",
  { headers: { "Authorization": "Bearer *** } }
);

Example Response

{
  "festival_id": 301,
  "festival_name": "Cambodia Town Film Festival",
  "count": 10,
  "page": 1,
  "per_page": 20,
  "total_pages": 1,
  "results": [
    {
      "id": 11,
      "festival_id": 301,
      "film_title": "Home Court",
      "film_director": "Erica Eng",
      "film_year": 2024,
      "film_genre": "",
      "film_category": "",
      "film_award": "Best Feature Documentary Film"
    },
    {
      "id": 12,
      "festival_id": 301,
      "film_title": "Meeting with Pol Pot",
      "film_director": "Rithy Panh",
      "film_year": 2025,
      "film_genre": "",
      "film_category": "",
      "film_award": "Opening Night Film"
    }
  ]
}

Describes what a festival actually programs, based on its historical roster of screened and awarded films, rather than only what its listing says it accepts. Returns years analyzed, dominant categories, common award categories, programming trends (documentary, animation, experimental), sample size, and a confidence level so you can judge how much to rely on it.

This is the endpoint to call when you want the answer to: "Based on what this festival has actually screened, how well does my film fit?"

Always up to date: profiles are recomputed automatically whenever a festival's roster changes, so last_verified_at stays current without any action from you. If a festival has too little history to analyze (<3 roster entries), the endpoint returns a low-confidence "insufficient data" profile rather than an error.

What you get

• sample_size, years_analyzed, year_range — how much history was available.
• dominant_categories — e.g. short, feature, documentary, animation, student, with counts and shares.
• common_award_categories and award_winners — the award types the festival hands out.
• programming_trends — documentary, animation, experimental, and music-video share.
• confidence and last_verified_at — honesty metadata. Confidence is derived from sample size and data coverage.

Runtime length and production-country distribution are not reported because the festival roster data does not carry those fields. We only publish analytics supported by the historical data we have.

Code Examples

curl -H "Authorization: Bearer *** \
     "https://festivalapi.com/v1/festivals/2629/programming-profile/"

resp = requests.get(
    "https://festivalapi.com/v1/festivals/2629/programming-profile/",
    headers={"Authorization": "Bearer *** }
)

const resp = await fetch(
  "https://festivalapi.com/v1/festivals/2629/programming-profile/",
  { headers: { "Authorization": "Bearer *** } }
);

Example Response

{
  "festival_id": 2629,
  "festival_name": "Africa International Film Festival (AFRIFF)",
  "sample_size": 85,
  "years_analyzed_count": 4,
  "years_analyzed": [2021, 2023, 2024, 2025],
  "year_range": {"min": 2021, "max": 2025},
  "dominant_categories": [
    {"category": "short", "count": 43, "share": 0.5059},
    {"category": "feature", "count": 18, "share": 0.2118},
    {"category": "documentary", "count": 14, "share": 0.1647}
  ],
  "common_award_categories": [
    {"award_category": "Best Documentary Short", "count": 1}
  ],
  "programming_trends": [
    {"trend": "Documentary", "category": "documentary", "count": 14, "share": 0.1647},
    {"trend": "Animation", "category": "animation", "count": 5, "share": 0.0588}
  ],
  "runtime_analysis": null,
  "production_country_distribution": null,
  "confidence": "very_high",
  "last_verified_at": "2026-08-11T00:00:00Z",
  "notes": ["Profile derived from festival roster entries."]
}

Returns festivals ranked by their Festival Score (0-100). The score factors in category match, deadline proximity, fee reasonableness, and genre alignment. Useful for finding the best festivals to submit to. Supports page/per_page pagination (default: 20 per page, max: 100).

Query Parameters

Code Examples

curl -H "Authorization: Bearer *** \
     "https://festivalapi.com/v1/festivals/scored/"

resp = requests.get(
    "https://festivalapi.com/v1/festivals/scored/",
    headers={"Authorization": "Bearer *** }
)

List all available countries with festival counts, ordered by count descending. Use this to discover which countries are covered, then filter by ?country= on the festivals endpoint.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://festivalapi.com/v1/countries

Response:

{
  "count": 20,
  "results": [
    {"country": "United States", "festival_count": 48},
    {"country": "United Kingdom", "festival_count": 15},
    {"country": "Canada", "festival_count": 12},
    ...
  ]
}

List all countries with festival counts. Use the full country name to filter festivals with the country parameter on /v1/festivals.

GET /v1/countries

Response:

{
  "count": 70,
  "results": [
    {"country": "United States", "count": 448},
    {"country": "United Kingdom", "count": 48},
    {"country": "Canada", "count": 46},
    {"country": "India", "count": 35},
    {"country": "Germany", "count": 37},
    {"country": "Italy", "count": 33},
    ...
  ]
}

A single unified feed of upcoming event dates and submission deadlines across all festivals, sorted by date. Power filmmaker calendars, submission CRMs, and embeddable festival widgets. Supports JSON and iCal (?export=ics) output so you can subscribe in Google/Apple Calendar.

Query Parameters

Code Examples

curl -H "Authorization: Bearer *** \
     "https://festivalapi.com/v1/calendar/?days=30"

resp = requests.get(
    "https://festivalapi.com/v1/calendar/?days=30",
    headers={"Authorization": "Bearer *** }
)

const resp = await fetch(
  "https://festivalapi.com/v1/calendar/?days=30",
  { headers: { "Authorization": "Bearer *** } }
);

Example Response

{
  "count": 12,
  "window": {"start": "2026-08-11", "end": "2026-09-10"},
  "results": [
    {
      "type": "deadline",
      "date": "2026-08-20",
      "deadline_stage": "regular",
      "festival_id": 301,
      "name": "Cambodia Town Film Festival",
      "city": "Long Beach", "state": "CA", "country": "United States",
      "categories": ["short_film", "feature", "documentary"],
      "submission_url": "https://filmfreeway.com/..."
    },
    {
      "type": "event",
      "date": "2026-09-05",
      "festival_id": 392,
      "name": "AFRIFF",
      "categories": ["feature", "documentary"]
    }
  ]
}

Festivals whose earliest upcoming submission deadline falls within the next N days. The nearest_deadline, deadline_stage, and days_remaining make it drop-in for email alerts, Slack/Discord notifications, and Zapier/n8n workflows that say "these deadlines close soon".

Query Parameters

Code Examples

curl -H "Authorization: Bearer *** \
     "https://festivalapi.com/v1/deadlines/closing-soon/?days=14"

resp = requests.get(
    "https://festivalapi.com/v1/deadlines/closing-soon/?days=14",
    headers={"Authorization": "Bearer *** }
)

const resp = await fetch(
  "https://festivalapi.com/v1/deadlines/closing-soon/?days=14",
  { headers: { "Authorization": "Bearer *** } }
);

Example Response

{
  "count": 5,
  "results": [
    {
      "festival_id": 944,
      "name": "Berlin Short Film Festival",
      "city": "Berlin", "country": "Germany",
      "categories": ["short_film"],
      "submission_url": "https://...",
      "nearest_deadline": "2026-08-18",
      "deadline_stage": "late",
      "days_remaining": 7
    }
  ]
}

Health check endpoint. No authentication required. Returns 200 OK when the API is operational.

{"status": "ok", "service": "Festival API"}

List all available category codes. Use these codes to filter festivals with the category parameter on /v1/festivals.

GET /v1/categories

Response:

{
  "count": 158,
  "results": [
    {"category": "short_film", "count": 60},
    {"category": "feature", "count": 55},
    {"category": "documentary", "count": 31},
    {"category": "animation", "count": 14},
    {"category": "horror", "count": 12},
    {"category": "sci_fi", "count": 5},
    {"category": "comedy", "count": 5},
    ...
  ]
}