*REST API › Introduction*

# REST API overview

> The Filmo REST API v1 is a JSON API over HTTPS at `https://app.filmo.io/api/v1`. You authenticate with an API key, and every response uses the same envelope.

## Base URL and a first call

Every path in this reference starts with `/api/v1`, on the origin `https://app.filmo.io`: for example, [`GET /api/v1/orders`](https://docs.filmo.io/rest-api/endpoint-reference/orders/list-orders). Requests and successful responses are JSON (`application/json`); errors are `application/problem+json`.

A good first call is [`GET /api/v1/account`](https://docs.filmo.io/rest-api/endpoint-reference/account/get-the-account). It needs the [`account:read`](https://docs.filmo.io/rest-api/guides/scopes#account:read) scope and returns the account, the timezone in which bare days are read, and the scopes of the key you used. To create a key, an administrator opens the API and MCP section of the account settings in Filmo (*Ajustes → API y MCP*); see [Authentication](https://docs.filmo.io/rest-api/guides/authentication).

*Your first call*

**cURL**

```bash
curl -sS --fail-with-body "${FILMO_BASE_URL:-https://app.filmo.io}/api/v1/account" \
  -H "Authorization: Bearer $FILMO_API_KEY"
```

**Node**

```javascript
const base = process.env.FILMO_BASE_URL ?? "https://app.filmo.io";
const res = await fetch(base + "/api/v1/account", {
  headers: { Authorization: `Bearer ${process.env.FILMO_API_KEY}` },
});
if (!res.ok) throw new Error(res.status + " " + (await res.text()));
const { data } = await res.json();
console.log(data.name, data.timezone, data.currency);
```

**Python**

```python
import os
import requests

base = os.environ.get("FILMO_BASE_URL", "https://app.filmo.io")
res = requests.get(
    base + "/api/v1/account",
    headers={"Authorization": f"Bearer {os.environ['FILMO_API_KEY']}"},
    timeout=30,
)
res.raise_for_status()
data = res.json()["data"]
print(data["name"], data["timezone"], data["currency"])
```

For a guided walk from a new key to your first write, follow the [quickstart](https://docs.filmo.io/quickstart). The OpenAPI file and the clients you can generate from it are covered in [OpenAPI file and generated clients](https://docs.filmo.io/rest-api/guides/openapi-and-clients); the reference of every operation is in the [OpenAPI reference](https://docs.filmo.io/rest-api/openapi).

## Response envelope

Every response from the API has one of three shapes.

| Kind | Shape | Used for |
| --- | --- | --- |
| List | `{ "data": [ … ], "pagination": { "nextCursor", "hasMore", "total"? } }` | Collections such as orders or contacts. |
| Single resource | `{ "data": { … } }` | Detail reads, creates and updates. |
| Error | An RFC 9457 problem in `application/problem+json`: `type`, `title`, `status`, `code`, `detail`, `requestId` | Any 4xx or 5xx the API produces. |

API responses carry an `X-Request-Id` header, and error bodies repeat it as `requestId`. Quote it when you contact support. The OAuth endpoints are the exception: they do not return it. The headers, the extra `meta` object some operations return and the statuses in use are in [Responses](https://docs.filmo.io/rest-api/guides/responses); every error code is in [Errors](https://docs.filmo.io/rest-api/guides/errors).

## Conventions at a glance

| Topic | Rule |
| --- | --- |
| Base URL | `https://app.filmo.io/api/v1` |
| Authentication | `Authorization: Bearer <API key>`. Only administrators create keys. |
| Money | Decimal strings with two decimals (`"1234.50"`), never floating-point numbers. |
| Dates | ISO 8601. Writes take an instant with an offset; responses use UTC. |
| Pagination | Opaque cursor. Page size `limit`: 50 by default, 500 at most. |
| Rate limits | 120 requests per minute per key, and 30 per minute shared by the three availability checks. |
| Retries | Send `Idempotency-Key` on writes. A key is remembered for 24 hours. |
| Concurrency | Detail reads return an `ETag`; send it back as `If-Match` to avoid overwriting a newer change. |
| Versioning | Additive changes within v1; breaking changes follow the documented notice periods. |

- **[Authentication](https://docs.filmo.io/rest-api/guides/authentication)**: Bearer keys, who owns a key and how to revoke it.
- **[OAuth](https://docs.filmo.io/rest-api/guides/oauth)**: When to use OAuth instead of a key.
- **[Scopes](https://docs.filmo.io/rest-api/guides/scopes)**: What each permission unlocks.
- **[Responses](https://docs.filmo.io/rest-api/guides/responses)**: Envelope variants, headers and statuses.
- **[Data types](https://docs.filmo.io/rest-api/guides/data-types)**: Money, dates, nulls and maps.
- **[Pagination](https://docs.filmo.io/rest-api/guides/pagination)**: Walk a list with the cursor.
- **[Filtering and sorting](https://docs.filmo.io/rest-api/guides/filtering-and-sorting)**: `sort`, date windows, list filters and search.
- **[Errors](https://docs.filmo.io/rest-api/guides/errors)**: Every code and when to retry.
- **[Rate limits](https://docs.filmo.io/rest-api/guides/rate-limits)**: Quotas, headers and backoff.
- **[Idempotency](https://docs.filmo.io/rest-api/guides/idempotency)**: Retry a write without duplicating it.
- **[Concurrency](https://docs.filmo.io/rest-api/guides/concurrency)**: Optimistic locking with `ETag` and `If-Match`.
- **[Versioning](https://docs.filmo.io/rest-api/guides/versioning)**: What changes within v1 and what never does.
- **[Testing](https://docs.filmo.io/rest-api/guides/testing)**: Try calls without hurting production data.
- **[Syncing data](https://docs.filmo.io/rest-api/guides/syncing-data)**: Keep another system in step by polling.
- **[Going live](https://docs.filmo.io/rest-api/guides/going-live)**: The checklist before production.

## Before you start

- Ask an administrator of the rental company to create the key, and decide who owns it: [Authentication](https://docs.filmo.io/rest-api/guides/authentication).
- Give the key only the permissions the integration uses: [Scopes](https://docs.filmo.io/rest-api/guides/scopes).
- Read what v1 covers, and what it does not, in [Capabilities and limits](https://docs.filmo.io/further-reading/capabilities-and-limits).
- Check which add-ons your account has: the API and MCP are included in any paid plan and are not an add-on, but a resource that belongs to a module with an add-on you have not contracted answers 402 [`addon_required`](https://docs.filmo.io/rest-api/errors/addon_required). See [Plans and add-ons](https://docs.filmo.io/concepts/plans-and-add-ons).
- A key works on the live data of the account it belongs to. Read [Testing](https://docs.filmo.io/rest-api/guides/testing) before your first write.
- Before you go to production, work through [Going live](https://docs.filmo.io/rest-api/guides/going-live).

## Versioning and compatibility

Check the contract version returned by [`GET /api/v1/account`](https://docs.filmo.io/rest-api/endpoint-reference/account/get-the-account) or published in the OpenAPI file. The compatibility rules and notice periods are documented in [Versioning](https://docs.filmo.io/rest-api/guides/versioning).

## Keeping your data in sync

v1 does not send webhooks. To keep another system in step with Filmo, poll incrementally: ask each list that has `updated*` filters for the records that changed since your last pass. [Syncing data](https://docs.filmo.io/rest-api/guides/syncing-data) describes an algorithm that does not skip records and how to detect deletions.

## Use it from an AI assistant

Every operation is also an MCP tool at `https://app.filmo.io/api/v1/mcp`, with the same key and scopes. See the [MCP overview](https://docs.filmo.io/mcp/overview).

---

Canonical URL: https://docs.filmo.io/rest-api/overview  
Last updated: 2026-10-09