*REST API › Guides*

# OpenAPI file and generated clients

> Filmo publishes its whole API as an OpenAPI 3.1 file. Use it to generate a typed client, to import the API into Postman, Insomnia or Bruno, or to run a mock server on your machine.

## Download the file

- JSON: `https://docs.filmo.io/openapi.json`
- YAML: `https://docs.filmo.io/openapi.yaml`

Both files describe the same contract. The version and the date of the snapshot these docs are built from are on the [OpenAPI reference](https://docs.filmo.io/rest-api/openapi) page, together with an index of every schema. The compatibility policy is described in [Versioning](https://docs.filmo.io/rest-api/guides/versioning). Whatever your tool takes as the server, send requests to `https://app.filmo.io`.

## What is in the file

- It is OpenAPI 3.1. A nullable value is written as `type: ["string", "null"]`, and unions use `anyOf`. Tools that only understand 3.0 misread both.
- Every operation has a stable `operationId`, the name the docs use ([`GET /api/v1/orders`](https://docs.filmo.io/rest-api/endpoint-reference/orders/list-orders), [`POST /api/v1/orders`](https://docs.filmo.io/rest-api/endpoint-reference/orders/create-an-order)).
- Schema names end in `Dto` for what the API returns and in `Body` for what you send (`OrderUpdateBody`). Generated clients expose them as type names.
- Money is a decimal string such as `"1234.50"`, never a float. Keep it as a string or a decimal type in your client.
- Each operation lists its scope in `x-required-scope` and its quotas in `x-rateLimit`.

## Generate a client

### TypeScript types with openapi-typescript

```bash
npx openapi-typescript https://docs.filmo.io/openapi.json -o filmo.d.ts
```

Pair the types with a small fetch wrapper such as openapi-fetch. The path keys include the `/api/v1` prefix.

*client.ts*

```typescript
import createClient from "openapi-fetch";
import type { paths } from "./filmo";

const client = createClient<paths>({
  baseUrl: process.env.FILMO_BASE_URL ?? "https://app.filmo.io",
  headers: { Authorization: `Bearer ${process.env.FILMO_API_KEY}` },
});

const { data, error } = await client.GET("/api/v1/account");
if (error) throw new Error(error.code);
console.log(data.data.name);
```

### Other languages with openapi-generator

OpenAPI Generator covers `typescript-fetch`, `python`, `csharp`, `java`, `php` and `go`, among others. Set the base path to `https://app.filmo.io` in the generated configuration, and send the key as a bearer token.

```bash
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.filmo.io/openapi.json \
  -g typescript-fetch \
  -o ./filmo-client
```

### Python with openapi-python-client

```bash
openapi-python-client generate --url https://docs.filmo.io/openapi.json
```

The availability responses are unions: each entry is one of several named schemas (a result, or an entry that says the item or resource was not found). Generators differ in how they handle `anyOf`, so generate the client and try the availability operations before you rely on them. The status of each generator, with the version tested and the known problems, is in the table under Generators we test.

## Generators we test

Filmo runs generators against the file. For each tool, the table gives the version tested, the options used, the result and the known problems.

| Tool | Version | Date | Options | Result | Known issues |
| --- | --- | --- | --- | --- | --- |
| openapi-typescript | 7.13.0 | 2026-10-09 | defaults (`openapi-typescript <spec> -o schema.ts`) | Generates and compiles | — |
| openapi-python-client | 0.29.1 | 2026-10-09 | defaults (`generate --path <spec>`) | Generates and compiles | — |
| openapi-generator (typescript-fetch) | 7.17.0 | 2026-10-09 | `-g typescript-fetch` | Generates and compiles | — |
| openapi-generator (python) | 7.17.0 | 2026-10-09 | `-g python` | Generates and compiles | Compiles, with a SyntaxWarning (invalid escape sequence `\&`) in `setup.py`: the generator pastes `info.description` into a string literal. |
| openapi-generator (csharp) | 7.17.0 | 2026-10-09 | `-g csharp` | Generates; not compiled (no dotnet in the verification environment) | Not compiled: no dotnet in the verification environment. |
| openapi-generator (java) | 7.17.0 | 2026-10-09 | `-g java` (default okhttp-gson library) | Generates and compiles | — |
| openapi-generator (java, native) | 7.17.0 | 2026-10-09 | `-g java --library native` | Generates and compiles | — |
| openapi-generator (php) | 7.17.0 | 2026-10-09 | `-g php` | Generates and passes `php -l` | — |
| openapi-generator (go) | 7.17.0 | 2026-10-09 | `-g go` | Generates and compiles | — |

## Import it in Postman, Insomnia or Bruno

1. **Import by link** In the import dialog of your tool, choose the option to import from a link or URL and paste `https://docs.filmo.io/openapi.json`. Importing the downloaded file also works.
2. **Set the base URL** Check the server the importer picked and set it to `https://app.filmo.io`.
3. **Add the key** Choose bearer token authentication and store the key as a secret variable or environment value, never in the collection itself.
4. **Make your first call** Run [`GET /api/v1/account`](https://docs.filmo.io/rest-api/endpoint-reference/account/get-the-account) to confirm the key and see its scopes.

If an importer shows odd types, the cause is usually the `type: [..., "null"]` or `anyOf` notation. The request still works.

## Make generated clients tolerant

- Closed enums: a new status or kind can arrive within v1 as an additive change. If your generator can map unknown enum values to a fallback, turn that on; if not, wrap response parsing so one unknown value does not fail the whole call.
- Strict response validation: do not reject unknown properties.
- Regenerate on purpose. Read the changelog first, then regenerate and review the diff of the generated code.

## Mock the API locally with Prism

Prism serves a fake API from the OpenAPI file. Use it to exercise your parsing, your error handling and your write paths without touching real data.

```bash
npm install --global @stoplight/prism-cli
prism mock -d https://docs.filmo.io/openapi.json

# In another terminal. Prism listens on port 4010 by default.
curl -s http://127.0.0.1:4010/api/v1/account -H "Authorization: Bearer $FILMO_API_KEY"
```

A mock returns generated data. Decimal fields come back as placeholder strings such as `"string"`, not amounts like `"1234.50"`, and the mock stores nothing, so it cannot show idempotent replays, ETag changes or the real rate limits. For those, follow the testing guide.

More on safe ways to test: [Testing](https://docs.filmo.io/rest-api/guides/testing).

---

Canonical URL: https://docs.filmo.io/rest-api/guides/openapi-and-clients  
Last updated: 2026-10-09