# Filmfreeway — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and discover film festivals worldwide with detailed information including deadlines, submission categories, fees, rules, and organizer contacts. Access comprehensive festival profiles, photos, and grant opportunities listed on FilmFreeway.

**Category:** Entertainment | **Website:** [filmfreeway.com/](https://filmfreeway.com/) | **Docs:** [parse.bot/marketplace/d5bde951-45a0-4792-86f2-3b816d9eb99c/filmfreeway-com-api](https://parse.bot/marketplace/d5bde951-45a0-4792-86f2-3b816d9eb99c/filmfreeway-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/filmfreeway/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get festival categories and fees

Fetch submission categories and their associated fee schedules for a festival by its slug. Each category lists fees per deadline tier (early, regular, final, extended) with standard and Gold Member pricing.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Festival URL slug (e.g. 'NantucketFilmFestival'). Obtainable from search_festivals results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/filmfreeway/get-festival-categories-and-fees \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"slug":"<string>"}'
```

### Get festival details

Fetch comprehensive details for one festival by its slug. Returns description, deadlines, submission categories with fees, rules, awards, organizers, and contact info. The slug is available from search_festivals or search_festivals_by_category results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Festival URL slug (e.g. 'NantucketFilmFestival'). Obtainable from search_festivals results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/filmfreeway/get-festival-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"slug":"<string>"}'
```

### Get festival photos

Fetch the photo gallery for a festival. Returns an array of photo objects with dimensions and captions. May be empty if the festival has no uploaded photos.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Festival URL slug (e.g. 'NantucketFilmFestival'). Obtainable from search_festivals results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/filmfreeway/get-festival-photos \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"slug":"<string>"}'
```

### Get festival rules

Fetch only the Rules & Terms text for a festival by its slug. Returns null if the festival has no published rules. Lighter than get_festival_details when only rules are needed.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Festival URL slug (e.g. 'NantucketFilmFestival'). Obtainable from search_festivals results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/filmfreeway/get-festival-rules \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"slug":"<string>"}'
```

### Search festivals

Full-text search over film festivals. Returns paginated summaries (up to 50 per page). Omitting the query returns all festivals ordered by relevance. Each summary carries the slug needed to fetch full details.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |
| `query` | string | No | Search keyword (e.g. 'grant', 'documentary'). Omitting returns all festivals. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/filmfreeway/search-festivals \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```

### Search festivals by category

Filter festivals by film submission category. Returns paginated summaries of festivals that accept submissions in the specified categories. Categories can be combined (comma-separated) for broader results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `categories` | string | Yes | Comma-separated list of category names to filter by. |
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/filmfreeway/search-festivals-by-category \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"categories":"<string>","page":"<integer>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.