Festival research gets harder to coordinate the moment a search leaves one person’s browser. A producer may ask for “short-documentary festivals in Canada under $50 with deadlines ahead,” but a copied spreadsheet row rarely preserves the exact filters, sort order, or date the list was created. A shareable search link solves the handoff problem: it turns a structured Festival API query into a reviewable piece of project context.
This pattern is useful for filmmaker portals, producer tools, and internal submission workflows. It does not expose an API key in the browser URL and it does not claim that a filtered result is a recommendation. It gives a team a stable way to reopen the same search, understand its constraints, and refresh it when festival data changes.
Define the public state separately from the API request
Start with the choices a collaborator should be able to read and edit. For a submission search, that may include category, genre, country, a fee ceiling, a deadline floor, and the result order. Festival API’s GET /v1/festivals endpoint supports structured filters for those constraints, including category, genre, country, deadline_after, fee_max, sort, and sort_dir.
Keep this public state in your application URL, not the API request URL. For example:
https://yourapp.example/festival-search?
category=short_film&genre=documentary&country=Canada&
fee_max=50&deadline_after=2026-10-01&sort=deadline&sort_dir=ascThe browser address is now a readable description of the search. Your server or backend-for-frontend can validate those values, attach the Bearer token securely, and make the Festival API request. Never put a Festival API key in a query string, a shareable link, or client-side source code.
Normalize before you save or share
URL parameters are flexible, which means two links can describe the same search in different ways. Normalize them before creating a saved search record or a shareable permalink. Trim strings, remove empty values, validate numeric limits, format dates as ISO dates, and use a consistent key order.
{
"category": "short_film",
"genre": "documentary",
"country": "Canada",
"fee_max": 50,
"deadline_after": "2026-10-01",
"sort": "deadline",
"sort_dir": "asc"
}That object is your search contract. It is more durable than a pasted result list because it captures what the team intended to find. It also makes it easy to compare two searches. If a producer changes only the fee ceiling from 50 to 75, the application can show that the scope changed rather than presenting a new list with no explanation.
Validate filters against supported values
Do not pass arbitrary user input straight through to the API. Use Festival API’s category and country endpoints to populate controlled choices where appropriate, and treat free-text search separately from structured filters. For the list endpoint, keep pagination parameters such as page and per_page out of the canonical search definition unless a specific page needs to be shared.
A small validation layer should also make the product honest about omissions. If a collaborator has not selected a country, omit that parameter instead of pretending the search is global by design. If a budget has not been approved, do not silently use a fee ceiling. The link should describe the constraints actually applied.
Fetch the query on the server
The server receives the normalized public state, constructs the API request, and keeps credentials private. Here is a simple request shape:
curl -G https://festivalapi.com/v1/festivals \
-H "Authorization: Bearer $FESTIVAL_API_KEY" \
--data-urlencode "category=short_film" \
--data-urlencode "genre=documentary" \
--data-urlencode "country=Canada" \
--data-urlencode "fee_max=50" \
--data-urlencode "deadline_after=2026-10-01" \
--data-urlencode "sort=deadline" \
--data-urlencode "sort_dir=asc"When sorting by deadline or event date, Festival API keeps unknown dates last. That behavior is useful in a review interface, but the interface should still label missing dates clearly. A sorted list is a prioritization aid, not proof that every record has complete submission information.
Add a snapshot without making the link stale
A permalink should reopen the current result set for the same filters. A decision trail needs more. When someone pins or shares a search for a meeting, store a separate snapshot containing the normalized query, retrieval time, result count, and the fields shown to reviewers. Keep the canonical link and the snapshot ID together.
- Canonical link: repeats the search against current data.
- Snapshot: records what the team saw at a particular time.
- Review notes: capture human judgment, next action, and owner outside the API result.
This distinction prevents a common workflow error. If a deadline or fee changes later, the refreshed link should reveal the new value, while the snapshot makes it possible to explain why the team made an earlier choice. Do not overwrite the review context just because the underlying data has changed.
Make the link useful in collaboration
Once a search is shareable, it can be placed in a producer brief, a Slack message, a CRM record, or a filmmaker-facing portal. Add a concise filter summary above the results, such as “Short documentary, Canada, up to $50, deadlines on or after October 1.” That summary gives a collaborator enough context before they inspect individual festivals.
The smallest useful implementation is a filter form, a normalized URL, a secure server-side API call, and a visible last-refreshed timestamp. Add named saved searches, snapshots, decision logs, and notifications only after the link accurately represents the query. The durable value is not another static list. It is a shared, repeatable way to investigate a changing festival landscape.
Review the Festival API documentation for the complete filter and response reference. When you are ready to connect saved searches to a real product workflow, see Festival API pricing and choose a refresh cadence that matches the submission decisions your users need to make.