{"openapi":"3.1.0","info":{"title":"API Cinéma","termsOfService":"https://api-cinema.com/en/terms","version":"v1 (0.1.0)","description":"Cinema showtimes in France and the United States (`country` filter). Authentication with an API key (`Authorization: Bearer ac_live_…`), created from the dashboard. Times are wall-clock times in each cinema's time zone (`cinema.timezone`).\n\nMovie titles, synopses, genres and TMDB ids come from [TMDB](https://www.themoviedb.org) once the movie is matched (`tmdbId` set); `rawTitle` keeps the title as published by the cinema. *This product uses the TMDB API but is not endorsed or certified by TMDB.*\n\nUse of the API is subject to the [terms of use](https://api-cinema.com/en/terms): one account per client, API keys kept server-side, no resale or bulk redistribution of the data, no working around the quotas.\n\n## Examples\n\nEvery call needs your API key. Lists are paginated (`limit`, `cursor`), and without `date` or `from` showtimes start from now, in each cinema's local time.\n\n### Every showtime of a film in France, from its Allociné or TMDB id\n\nThe Allociné id is the number in the film page URL (`allocine.fr/film/fichefilm_gen_cfilm=1000013045.html` for *L'Odyssée*); the TMDB id is the one in `themoviedb.org/movie/1368337`. You do not need our movie id:\n\n```bash\ncurl \"https://api.api-cinema.com/v1/showtimes?allocine_id=1000013045&country=FR&limit=100\" -H \"Authorization: Bearer ac_live_…\"\ncurl \"https://api.api-cinema.com/v1/showtimes?tmdb_id=1368337&country=FR&limit=100\" -H \"Authorization: Bearer ac_live_…\"\n```\n\nTo get our movie ids (for `/v1/movies/{id}`), look the film up by the same ids:\n\n```bash\ncurl \"https://api.api-cinema.com/v1/movies?allocine_id=1000013045\" -H \"Authorization: Bearer ac_live_…\"\n# → two rows, one per country, same tmdbId 1368337:\n#   { \"id\": \"065ec55d-…\", \"title\": \"L'Odyssée\", \"allocineId\": \"1000013045\", \"tmdbId\": 1368337 }\n#   { \"id\": \"e125e88f-…\", \"title\": \"The Odyssey\", \"allocineId\": null, \"tmdbId\": 1368337 }\n```\n\n### Every showtime of a film, from its name\n\nNo Allociné or TMDB id at hand? Search the film by name first, then read its showtimes:\n\n```bash\n# 1. find the film among the movies showing in France\ncurl \"https://api.api-cinema.com/v1/movies?q=spider&playing=true&country=FR\" -H \"Authorization: Bearer ac_live_…\"\n# → { \"id\": \"a1…\", \"title\": \"Spider-Man : Brand New Day\", \"rawTitle\": \"SPIDER-MAN : BRAND NEW DAY\", \"tmdbId\": 969681 }\n#   { \"id\": \"b2…\", \"title\": \"Spider-Man : Brand New Day\", \"rawTitle\": \"SPIDERMAN\", \"tmdbId\": 969681 }\n#   { \"id\": \"c3…\", \"title\": \"Spider-Man : New Generation\", \"rawTitle\": \"Spider-Man : New Generation\", \"tmdbId\": 324857 }\n\n# 2. pick the film, then every showtime of it (both rows above) by its tmdbId\ncurl \"https://api.api-cinema.com/v1/showtimes?tmdb_id=969681&country=FR&limit=100\" -H \"Authorization: Bearer ac_live_…\"\n```\n\nIf the film you picked has no `tmdbId` yet (`titleSource: \"raw\"`), read the showtimes of each row with `GET /v1/movies/{id}/showtimes` instead.\n\n**How the title search (`q`) works**\n\n- Your text and the titles are compared after the same normalization: lower case, accents and punctuation removed, a leading article dropped (`le`, `la`, `les`, `l'`, `un`, `une`, `des`, `the`, `a`, `an`). `L'Odyssée`, `l odyssee` and `ODYSSEE` are the same search.\n- It is a *contains* match on the title **as published by the cinema** (`rawTitle`), not on the TMDB title nor the original title: in France, `q=odyssee` finds *L'Odyssée* but `q=the odyssey` finds nothing (US rows carry the English title).\n- Cinemas write titles their own way (`SPIDERMAN`, `SPIDER-MAN : BRAND NEW DAY`): search a short, distinctive word (`spider`) rather than the full title.\n- Several films can match (`q=odyssee` also returns *2001 : L'Odyssée de l'espace*), and one film can come as several rows (one per published title or per country): pick by `title`, `year` or `tmdbId`, never blindly the first result, then continue with `tmdb_id`.\n- Add `playing=true` to keep only films with upcoming showtimes, and `country` to stay in one country. Results are sorted by title and paginated (`limit`, `offset`).\n\n### What's on in New York\n\n`city` is an exact match (\"New York\" leaves out \"Brooklyn\"): search around a point instead. Times Square, 5 km:\n\n```bash\ncurl \"https://api.api-cinema.com/v1/showtimes?country=US&near=40.758,-73.9855&radius_km=5&limit=200\" -H \"Authorization: Bearer ac_live_…\"\n```\n\nAdd `date=2026-09-25` for one day only; each showtime carries `cinema.distanceKm`. The cinemas themselves, nearest first:\n\n```bash\ncurl \"https://api.api-cinema.com/v1/cinemas?country=US&near=40.758,-73.9855&radius_km=5\" -H \"Authorization: Bearer ac_live_…\"\n```\n\n### Tonight near me, in original version with subtitles\n\nThe same search as a JSON body (`POST …/search`), easier to build from code:\n\n```js\nconst res = await fetch('https://api.api-cinema.com/v1/showtimes/search', {\n  method: 'POST',\n  headers: { 'Authorization': 'Bearer ac_live_…', 'Content-Type': 'application/json' },\n  body: JSON.stringify({\n    near: { lat: 45.764, lng: 4.8357, radiusKm: 3 }, // Lyon city centre\n    from: '2026-09-25T18:00', // tonight, local time of each cinema\n    to: '2026-09-25T23:59',\n    version: 'VOST',\n    include: ['movie', 'cinema'],\n    limit: 100,\n  }),\n})\nconst { data } = await res.json()\nfor (const s of data)\n  console.log(s.startsAt.slice(11, 16), s.movie.title, '—', s.cinema.name, `${s.cinema.distanceKm} km`)\n```\n\n### A cinema's programme for the week\n\nFind the cinema by name, then read its showtimes (the path takes its `id` or its `slug`):\n\n```bash\ncurl \"https://api.api-cinema.com/v1/cinemas?q=champo&country=FR\" -H \"Authorization: Bearer ac_live_…\"\n# → { \"id\": \"cnc_8422\", \"slug\": \"le-champo-paris-5e-arrondissement\", \"name\": \"Le Champo\", … }\ncurl \"https://api.api-cinema.com/v1/cinemas/le-champo-paris-5e-arrondissement/showtimes?from=2026-09-24&to=2026-09-30\" -H \"Authorization: Bearer ac_live_…\"\n```\n\nWithout `from` / `to`, a cinema's showtimes default to today. Past showtimes are kept 7 days.\n\nTo pick from the cinemas of one postal code (or ZIP code in the US), pass `zip_code`; its first digits are enough, `zip_code=69` lists a whole French department:\n\n```bash\ncurl \"https://api.api-cinema.com/v1/cinemas?zip_code=75005\" -H \"Authorization: Bearer ac_live_…\"\n```\n\n### Films showing now in a country\n\n```bash\ncurl \"https://api.api-cinema.com/v1/movies?playing=true&country=FR&limit=100\" -H \"Authorization: Bearer ac_live_…\"\ncurl \"https://api.api-cinema.com/v1/movies?q=odyssey&playing=true&country=US\" -H \"Authorization: Bearer ac_live_…\"\n```\n\nGroup films by `tmdbId`: the same film has one `id` per country, and one per published title until it is matched on TMDB.\n\n### Keep a local copy up to date\n\nImport everything once, then only fetch changes with `updated_since`: see *Incremental sync* below.\n\n## What's new\n\n### 2026-10-30 — Find cinemas by postal / ZIP code\n\nNew filter on `/v1/cinemas`: `zip_code` (`zipCode` in the body of `POST /v1/cinemas/search`, and on the MCP tool `search_cinemas`). It keeps cinemas whose `postalCode` starts with the given digits, 2 to 5: `zip_code=75005` for one code, `zip_code=75` for a whole French department, `zip_code=100` for a range of US ZIP codes. It combines with the other filters. Cinemas without a known `postalCode` are left out.\n\n**What to do if you already use the API**\n\n- Nothing to do. If you turned a postal code into a city or a point to search, you can pass it directly.\n\n### 2026-10-29 — One account per client: `403 account_suspended`\n\nWhen an account is signed up from a connection that already has one, its API access is suspended: every request answers `403` with the code `account_suspended`, and the account receives an e-mail. The terms of use allow one account per client (section 2); the account created first is not affected.\n\n**What to do if you already use the API**\n\n- Nothing to do for a single account. If several people or companies share one connection (a shared office, for instance), write to support@api-cinema.com.\n\n### 2026-10-22 — Free plan: 150 requests a week, non-commercial use\n\nThe Free plan now allows 150 requests a week (was 250), all its API keys together, and is reserved for trials and non-commercial projects (terms of use, section 4). A website or app that earns revenue or serves a business, a cinema’s website included, needs a paid plan (Starter, €12 a month, 10,000 requests a week). Paid plans and accounts on a quote are unchanged.\n\n**What to do if you already use the API**\n\n- If you are on the Free plan, check your weekly use in the dashboard: past 150 requests the API answers `429` with `weekly_quota_exceeded` until Monday 00:00 UTC.\n- If your use is commercial, move to a paid plan from the dashboard.\n\n### 2026-10-22 — `city=Paris` finds every arrondissement\n\nParis cinemas are filed by arrondissement (`\"city\": \"Paris 5e Arrondissement\"`), so `city=Paris` used to return nothing. It now matches Paris and all its arrondissements, on `/v1/cinemas`, `/v1/showtimes` and their `search` variants; an arrondissement (`city=Paris 5e Arrondissement`) still works on its own. Every other city keeps an exact match.\n\n**What to do if you already use the API**\n\n- If you worked around it by listing the arrondissements or by searching around a point, you can switch to `city=Paris`.\n\n### 2026-10-19 — One week of past showtimes\n\nPast showtimes are now kept 7 days: a `date` or `from` earlier than a week ago returns nothing for the days before. Upcoming showtimes and `updated_since` sync are unchanged; past showtimes simply drop out after a week, without a removal entry.\n\n**What to do if you already use the API**\n\n- If you need a longer history, store the showtimes on your side as you import them.\n\n### 2026-09-27 — Faster responses, new database\n\nThe API now runs on a new database. Heavy queries are much faster (films showing in a country, all the showtimes of a film: 2 to 7 times), the others as fast or faster. Responses are unchanged, with two small improvements: `q` searches now ignore the case of accented letters too (an upper-case accented name finds its lower-case spelling), and films sharing a title are always listed in the same order. A revoked API key is now refused within a minute rather than immediately.\n\n### 2026-09-24 — Terms of use\n\nThe API now has published terms of use, linked at the top of this page and from the OpenAPI `info.termsOfService`. They spell out what was already expected: one account per client, API keys kept server-side and never shared, no resale or bulk redistribution of the data, and no working around the quotas with extra keys or accounts.\n\n**What to do if you already use the API**\n\n- Check that your API keys are only used server-side (never in a web page or mobile app).\n- If you need more volume, ask support rather than adding keys or accounts.\n\n### 2026-09-24 — Weekly quota per account\n\nAn account can now have a weekly request quota (Monday 00:00 UTC → Sunday, all its API keys together). When it has one, responses carry `X-Weekly-Quota-Limit`, `X-Weekly-Quota-Remaining` and `X-Weekly-Quota-Reset`, and past the quota the API answers `429` with the code `weekly_quota_exceeded`. Accounts without a weekly quota see no change.\n\n**What to do if you already use the API**\n\n- If you handle `429` responses, also expect the `weekly_quota_exceeded` code: its `Retry-After` can be several days.\n\n### 2026-09-23 — JSON search (POST)\n\nEvery list with filters now has a `POST …/search` twin taking its filters in a JSON body, with typed values and camelCase names (`tmdbId`, `near: { lat, lng, radiusKm }`, `include: [\"movie\"]`…): no more long URLs to build. Same response, same pagination (`cursor`), same quota; unknown keys are refused (400).\n\n| GET (URL parameters) | POST (JSON body) |\n| --- | --- |\n| `/v1/showtimes` | `/v1/showtimes/search` |\n| `/v1/cinemas` | `/v1/cinemas/search` |\n| `/v1/movies` | `/v1/movies/search` |\n| `/v1/cinemas/{id}/showtimes` | `/v1/cinemas/{id}/showtimes/search` |\n| `/v1/movies/{id}/showtimes` | `/v1/movies/{id}/showtimes/search` |\n\n### 2026-09-23 — Showtimes by TMDB or Allociné id\n\n`/v1/showtimes` and `/v1/movies` accept `tmdb_id` and `allocine_id` (the id in `allocine.fr/film/fichefilm_gen_cfilm=<id>.html`): every showtime of a film, whatever the title each cinema publishes. `allocine_id` also finds showtimes read from other sources once the film is matched on TMDB. Movies expose a new `allocineId` field (set when the movie was read from Allociné).\n\n### 2026-09-23 — Cinemas in the United States\n\nThe API now covers cinemas in the United States as well as France. **Without a `country` parameter, lists return both countries**: `/v1/cinemas`, `/v1/showtimes`, `/v1/movies` and `/v1/movies/{id}/showtimes` include US cinemas and showtimes.\n\n- New `country` filter (`FR` or `US`) on these four lists, and in the MCP tools.\n- New cinema fields: `country` and `timezone` (IANA zone, e.g. `America/New_York`). In the US, `region` holds the state code (`NY`) and `postalCode` the ZIP code.\n- `startsAt` is still a local time without offset, but it is now **the cinema's local time** (`cinema.timezone`), no longer always Europe/Paris.\n- Without `date` or `from`, \"now\" and \"today\" are evaluated in each cinema's time zone. `date`, `from` and `to` are read in each cinema's local time.\n- Outside France, `cncId`, `inseeCode`, `department` and `artEtEssai` are `null`.\n- US showtimes: `version` is `VO` (original version) or `VOST` (subtitled), `UNKNOWN` for a dubbed screening.\n- Movies of US cinemas have their own rows, separate from French ones, with TMDB title, synopsis and genres **in English**. A film shown in both countries therefore has one `id` per country and the same `tmdbId`.\n\n**What to do if you already use the API**\n\n- To keep exactly your current scope, add `country=FR` to your list calls (cinemas, showtimes, movies, showtimes of a movie). Calls by id (`/v1/cinemas/{id}`, `/v1/movies/{id}`) do not change.\n- To turn `startsAt` into an instant (UTC, display in another zone), use `cinema.timezone` instead of assuming Europe/Paris.\n- If your code reads `cncId`, `inseeCode`, `department` or `artEtEssai`, accept `null` for cinemas outside France.\n- If you group movies by film, use `tmdbId` rather than `id` or the title (one `id` per country).\n- If you validate `country` or `timezone` against a strict schema, add both fields.\n\n## Versions\n\nThe URL carries the major version (`/v1/…`); the selector at the top of the page shows the documentation of each version, the latest by default.\n\n- **Additions** (new routes, new optional parameters, new response fields) ship to every supported version without a version change: ignore fields you do not know.\n- A **breaking change** (another default behaviour, a removed or renamed field, a stricter validation) opens a new major version; your current version does not change.\n- A replaced version keeps being served for at least 6 months. Its responses then carry the `Deprecation`, `Sunset` (last day of service) and `Link: <…>; rel=\"successor-version\"` headers.\n\n| Version | Released | Status |\n| --- | --- | --- |\n| `/v1` (this page) | 2026-09-15 | current |\n\n## Full showtime import\n\n- Walk `GET /v1/showtimes` with `limit=1000` and `cursor` (the `meta.nextCursor` of the previous page).\n- `include` picks the nested objects: `movie,cinema` by default, `include=movie` or `include=` (empty) for much lighter pages. `movieId` and `cinemaId` are always there: load movies and cinemas once, separately.\n- Group one film by `movie.tmdbId`: two cinemas publishing different titles give two `movie.id` for the same `tmdbId`. `movie.titleSource` is `tmdb` or `raw`; `GET /v1/movies/unmatched` lists showing movies still without a `tmdbId`.\n- `cinema.programmeCheckedAt` is the last successful read of the cinema's programme: past 2 days, it may be stale.\n- `showtime.id` is stable: a showtime keeps its id as long as its cinema, movie, time and version do not change.\n\n## JSON search\n\nRather than a long URL, send the filters in a JSON body (camelCase names, typed values): every list has its `POST …/search` twin (`/v1/showtimes/search`, `/v1/cinemas/search`, `/v1/movies/search`, `/v1/cinemas/{id}/showtimes/search`, `/v1/movies/{id}/showtimes/search`). Response, pagination and quota are the same as with `GET`.\n\n```js\nconst res = await fetch('https://api.api-cinema.com/v1/showtimes/search', {\n  method: 'POST',\n  headers: { 'Authorization': 'Bearer ac_live_…', 'Content-Type': 'application/json' },\n  body: JSON.stringify({\n    country: 'FR',\n    allocineId: '1000013045',\n    near: { lat: 45.764, lng: 4.8357, radiusKm: 5 },\n    from: '2026-09-25T18:00',\n    to: '2026-09-26',\n    version: 'VOST',\n    include: ['movie'],\n    limit: 100,\n  }),\n})\nconst { data, meta } = await res.json() // next page: same body + cursor: meta.nextCursor\n```\n\n## Incremental sync\n\n1. Full import: walk `GET /v1/showtimes` and keep `meta.syncedAt` of the **first** page.\n2. Then: `GET /v1/showtimes?updated_since=<syncedAt>` (same `from`/`to`… filters) returns only the showtimes added, changed or removed since, ordered by `updatedAt`, with the same `cursor`. Keep the `meta.syncedAt` of its first page again.\n3. A showtime with `removedAt` set is no longer listed by the cinema (cancelled or withdrawn): delete it on your side. Normal lists never return a removed showtime.\n4. `GET /v1/movies?updated_since=…` gives the changed movies (TMDB match, title, synopsis).\n\n`syncedAt` is taken a few minutes before the request: a showtime may come twice, apply changes by `id`. Removed showtimes are kept 30 days: past that without a sync, do a full import again.\n\n## Rate limits\n\nEach API key has a request quota per 60-second window, set by its plan. Windows start at every full minute (hh:mm:00).\n\n| Plan | Requests per minute, per key |\n| --- | --- |\n| Standard | 60 |\n| Pro | 600 |\n\nEvery authenticated response gives the key's exact count:\n\n```http\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 41\nX-RateLimit-Reset: 23\nRateLimit-Policy: \"standard\";q=60;w=60\nRateLimit: \"standard\";r=41;t=23\n```\n\n`X-RateLimit-Remaining` counts the current request; `X-RateLimit-Reset` is the number of seconds before the next window. The last two lines follow the IETF draft *RateLimit header fields*.\n\nPast the quota, the API answers `429 Too Many Requests` with `Retry-After` (seconds until the next window) and `X-RateLimit-Remaining: 0`. The body details the limit:\n\n```json\n{\n  \"error\": {\n    \"code\": \"rate_limited\",\n    \"message\": \"Rate limit exceeded: 60 requests per 60 s for this API key. Retry in 23 s.\",\n    \"details\": { \"limit\": 60, \"windowSeconds\": 60, \"retryAfterSeconds\": 23, \"plan\": \"standard\" }\n  }\n}\n```\n\nWait for `Retry-After` before retrying: refused requests count in the window too. For a higher quota, contact support from the dashboard: spreading requests over several keys or accounts to get past it breaks the [terms of use](https://api-cinema.com/en/terms).\n\n### Weekly quota\n\nSome accounts also have a weekly quota, set with your plan: a number of requests per week (Monday 00:00 UTC → Sunday), counting every API key of the account together. When your account has one, every response carries:\n\n```http\nX-Weekly-Quota-Limit: 10000\nX-Weekly-Quota-Remaining: 8412\nX-Weekly-Quota-Reset: 302400\n```\n\n`X-Weekly-Quota-Remaining` counts the current request; `X-Weekly-Quota-Reset` is the number of seconds until Monday 00:00 UTC. Past the quota, the API answers `429` with the code `weekly_quota_exceeded` and `Retry-After` set to the reset; refused requests do not count. Without a weekly quota, these headers are absent.\n\n## Walking every showtime\n\nShowtime lists (`/v1/showtimes`, `/v1/cinemas/{id}/showtimes`, `/v1/movies/{id}/showtimes`) accept `limit` up to 1000. To go through everything, follow the cursor rather than `offset`: the order is stable (`startsAt` then `id`) and every page answers as fast as the first one.\n\n```bash\ncurl \"https://api.api-cinema.com/v1/showtimes?from=2026-09-16&to=2026-09-30&limit=1000\" -H \"Authorization: Bearer ac_live_…\"\n# meta.nextCursor = \"WyIyMDI2LTA5LTE2VDE0OjAwOjAwIiwiLi4uIl0\"\ncurl \"https://api.api-cinema.com/v1/showtimes?from=2026-09-16&to=2026-09-30&limit=1000&cursor=WyIyMDI2LTA5LTE2VDE0OjAwOjAwIiwiLi4uIl0\" -H \"Authorization: Bearer ac_live_…\"\n```\n\nRepeat with the same filters until `meta.nextCursor` is `null`. `meta.total` is only computed on the first page (without a cursor). The cursor combines with neither `offset` nor `near`.\n\n## MCP server\n\nThe API is also available as an [MCP](https://modelcontextprotocol.io) server (Streamable HTTP), to query showtimes from Claude, Cursor or any compatible client. The server takes the same API key as the REST API; each tool call counts as one request and follows the key's rate limit.\n\n**Address**: `https://api.api-cinema.com/mcp`\n\n**Claude Code**\n\n```bash\nclaude mcp add --transport http api-cinema https://api.api-cinema.com/mcp --header \"Authorization: Bearer ac_live_…\"\n```\n\n**Claude Desktop, Cursor and clients configured in JSON**\n\n```json\n{\n  \"mcpServers\": {\n    \"api-cinema\": {\n      \"type\": \"http\",\n      \"url\": \"https://api.api-cinema.com/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer ac_live_…\" }\n    }\n  }\n}\n```\n\n**Available tools** (read-only, 20 results by default)\n\n- `search_showtimes`: Upcoming cinema showtimes in France and the United States, filtered by country, by film (movie_id, TMDB or Allociné id), by city, by distance around a point, by movie, by day or time range and by language version. Each result includes the movie and the cinema.\n- `search_cinemas`: Cinemas in France and the United States by country, city, name, postal / ZIP code, or around a point (sorted by distance, with distanceKm).\n- `get_cinema`: Details of one cinema (address, coordinates, screens, website, ticketing) by id or slug.\n- `cinema_showtimes`: Programme of one cinema, by id or slug. Defaults to today.\n- `search_movies`: Movies by title (accent and case insensitive). Set playing to true to keep only movies with upcoming showtimes, and country to restrict to one country.\n- `movie_showtimes`: Upcoming showtimes of one movie, optionally in a country, a city or around a point. Get the movie_id from search_movies.\n"},"servers":[{"url":"https://api.api-cinema.com"}],"tags":[{"name":"Cinemas"},{"name":"Showtimes"},{"name":"Movies"},{"name":"Meta"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key created from the dashboard, e.g. `ac_live_…`"}},"schemas":{"CinemaList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Cinema"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]},"Cinema":{"type":"object","properties":{"id":{"type":"string","example":"6b1f…"},"slug":{"type":"string","example":"paris-le-champo"},"name":{"type":"string","example":"Le Champo"},"address":{"type":["string","null"],"example":"51 rue des Écoles"},"city":{"type":"string","example":"Paris"},"country":{"type":"string","enum":["FR","US"],"example":"FR","description":"ISO 3166-1 alpha-2"},"timezone":{"type":"string","example":"Europe/Paris","description":"IANA time zone of the cinema: its showtimes `startsAt` are wall-clock times in this zone"},"postalCode":{"type":["string","null"],"example":"75005","description":"Postal code (FR) or ZIP code (US)"},"inseeCode":{"type":["string","null"],"example":"75105","description":"France only: INSEE code of the municipality (CNC); set even when `postalCode` is missing"},"department":{"type":["string","null"],"example":"75","description":"France only: département code (CNC)"},"region":{"type":["string","null"],"example":"Île-de-France","description":"Région (FR) or state code, e.g. \"NY\" (US)"},"lat":{"type":["number","null"],"example":48.8497},"lng":{"type":["number","null"],"example":2.3437},"website":{"type":["string","null"],"example":"https://www.lechampo.com"},"cncId":{"type":["integer","null"],"example":188341,"description":"France only: CNC id of the establishment"},"screens":{"type":["integer","null"],"example":3},"seats":{"type":["integer","null"],"example":589},"artEtEssai":{"type":["boolean","null"],"example":true,"description":"France only: rated \"Art et Essai\" (arthouse label)"},"ticketingUrl":{"type":["string","null"],"example":"https://www.lechampo.com/billetterie"},"phone":{"type":["string","null"],"example":"+33 1 43 54 51 60"},"email":{"type":["string","null"],"example":"contact@lechampo.com"},"active":{"type":"boolean"},"programmeCheckedAt":{"type":["string","null"],"example":"2026-09-16T12:15:03.000Z","description":"Last successful read of the cinema's programme (ISO 8601, UTC); null when it was never read. A programme read more than 2 days ago may be stale"},"distanceKm":{"type":"number","description":"Only present when `near` is given","example":1.2}},"required":["id","slug","name","address","city","country","timezone","postalCode","inseeCode","department","region","lat","lng","website","cncId","screens","seats","artEtEssai","ticketingUrl","phone","email","active","programmeCheckedAt"]},"Meta":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"required":["limit","offset"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"not_found"},"message":{"type":"string","example":"Cinema not found"},"details":{}},"required":["code","message"]}},"required":["error"]},"CinemaSearch":{"type":"object","properties":{"country":{"type":"string","enum":["FR","US"],"description":"Optional. Only cinemas of this country. Default: every country.","example":"FR"},"city":{"type":"string","minLength":1,"description":"Optional. Exact city name; `Paris` also matches its arrondissements.","example":"Lyon"},"q":{"type":"string","minLength":1,"description":"Optional. Name contains.","example":"champo"},"zipCode":{"type":"string","pattern":"^\\d{2,5}$","description":"Optional. Postal code (FR) or ZIP code (US) starts with: `75005` for one code, `75` for a whole French department, `100` for a range of US ZIP codes. 2 to 5 digits.","example":"69002"},"active":{"type":"boolean","default":true,"description":"Optional. Open cinemas (default) or closed ones."},"near":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusKm":{"type":"number","exclusiveMinimum":0,"maximum":100,"default":10}},"required":["lat","lng"],"additionalProperties":false,"description":"Optional. Centre point and radius (default 10 km); results carry `distanceKm`.","example":{"lat":45.764,"lng":4.8357,"radiusKm":5}},"limit":{"type":"integer","minimum":1,"maximum":200,"default":50,"example":50,"description":"Optional."},"offset":{"type":"integer","minimum":0,"default":0,"example":0,"description":"Optional."}},"additionalProperties":false,"example":{"country":"FR","near":{"lat":48.8566,"lng":2.3522,"radiusKm":3}}},"ShowtimeList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Showtime"}},"meta":{"$ref":"#/components/schemas/ShowtimeMeta"}},"required":["data","meta"]},"Showtime":{"type":"object","properties":{"id":{"type":"string"},"cinemaId":{"type":"string","description":"Always present, also when `cinema` is left out with `include`"},"movieId":{"type":"string","description":"Always present, also when `movie` is left out with `include`"},"startsAt":{"type":"string","description":"Wall-clock datetime in the cinema's time zone (`cinema.timezone`), no offset","example":"2026-09-15T20:30:00"},"version":{"type":"string","enum":["VF","VO","VOST","VFST","UNKNOWN"],"example":"VOST"},"format":{"type":"string","enum":["2D","3D","IMAX","4DX","DOLBY","UNKNOWN"],"example":"2D"},"room":{"type":["string","null"],"example":"Salle 1"},"bookingUrl":{"type":["string","null"]},"updatedAt":{"type":"string","description":"Last insert, change or removal of this showtime (ISO 8601, UTC)","example":"2026-09-16T12:15:03.412Z"},"removedAt":{"type":["string","null"],"description":"Set when the cinema no longer lists this showtime (cancelled or withdrawn). Only returned with `updated_since`; normal lists hide removed showtimes","example":null},"movie":{"$ref":"#/components/schemas/Movie"},"cinema":{"allOf":[{"$ref":"#/components/schemas/Cinema"},{"description":"Left out when `include` does not list `cinema`"}]}},"required":["id","cinemaId","movieId","startsAt","version","format","room","bookingUrl","updatedAt","removedAt"]},"Movie":{"type":"object","properties":{"id":{"type":"string","example":"9a2c…"},"title":{"type":"string","description":"Clean title from TMDB when the movie is matched (tmdbId set): French for French cinemas, English for US ones; otherwise the title as published by the first cinema","example":"Dune : Deuxième partie"},"rawTitle":{"type":["string","null"],"description":"Title as first published by a cinema, before cleanup","example":"DUNE 2"},"originalTitle":{"type":["string","null"],"example":"Dune: Part Two"},"year":{"type":["integer","null"],"example":2024},"durationMin":{"type":["integer","null"],"example":166},"director":{"type":["string","null"],"example":"Denis Villeneuve"},"synopsis":{"type":["string","null"],"description":"Synopsis (TMDB), French or English like `title`"},"genres":{"type":"array","items":{"type":"string"},"description":"Genre names (TMDB), French or English like `title`; empty when unknown","example":["Science-Fiction","Aventure"]},"posterUrl":{"type":["string","null"]},"allocineId":{"type":["string","null"],"description":"Allociné film id, when the movie was read from Allociné (France); filter showtimes with `allocine_id`","example":"1000013045"},"tmdbId":{"type":["integer","null"],"description":"The Movie Database id, set when the movie was matched. Group showtimes of one film by `tmdbId`: cinemas publishing different titles (\"SPIDERMAN\", \"Spider-Man : Brand New Day\") give distinct `id`s with the same `tmdbId`, and a film shown in France and in the US has one `id` per country","example":693134},"updatedAt":{"type":"string","description":"Last change of the movie (TMDB match, alias, metadata), ISO 8601 UTC","example":"2026-09-16T12:15:03.412Z"},"titleSource":{"type":"string","enum":["tmdb","raw"],"description":"`tmdb`: title, synopsis and genres come from TMDB (tmdbId set); `raw`: title as published by the cinema, not matched yet","example":"tmdb"}},"required":["id","title","rawTitle","originalTitle","year","durationMin","director","synopsis","genres","posterUrl","allocineId","tmdbId","updatedAt","titleSource"],"description":"Left out when `include` does not list `movie`"},"ShowtimeMeta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"total":{"type":"integer","description":"Matching showtimes; omitted on pages requested with `cursor`"},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page"},"syncedAt":{"type":"string","description":"Keep the value of the first page of a walk and pass it as `updated_since` on your next sync (a few minutes before the request, so nothing written during the walk is missed; some rows may come twice)","example":"2026-09-16T11:55:00.000Z"}},"required":["nextCursor","syncedAt"]}]},"CinemaShowtimeSearch":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Optional. Whole day, in each cinema's local time.","example":"2026-09-25"},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}(?::\\d{2})?)?$","description":"Optional. YYYY-MM-DD or YYYY-MM-DDTHH:MM, in each cinema's local time. Defaults to now in each cinema's time zone.","example":"2026-09-25T18:00"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}(?::\\d{2})?)?$","description":"Optional. YYYY-MM-DD or YYYY-MM-DDTHH:MM, in each cinema's local time.","example":"2026-09-26"},"version":{"type":"string","enum":["VF","VO","VOST","VFST","UNKNOWN"],"example":"VOST","description":"Optional."},"include":{"type":"array","items":{"type":"string","enum":["movie","cinema"]},"description":"Optional. Nested objects to embed. Default both; `[]` returns only `movieId` / `cinemaId`.","example":["movie"]},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":50,"example":100,"description":"Optional."},"offset":{"type":"integer","minimum":0,"default":0,"example":0,"description":"Optional."},"cursor":{"type":"string","maxLength":200,"description":"Optional. `meta.nextCursor` of the previous page."}},"additionalProperties":false,"example":{"date":"2026-09-25","include":["movie"]}},"ShowtimeSearch":{"type":"object","properties":{"country":{"type":"string","enum":["FR","US"],"description":"Optional. Only cinemas of this country. Default: every country.","example":"FR"},"city":{"type":"string","minLength":1,"description":"Optional. Exact city name; `Paris` also matches its arrondissements.","example":"Lyon"},"cinemaId":{"type":"string","minLength":1,"description":"Optional. One cinema (id).","example":"cnc_188341"},"movieId":{"type":"string","minLength":1,"description":"Optional. One movie row (id)."},"tmdbId":{"type":"integer","exclusiveMinimum":0,"description":"Optional. Every showtime of this TMDB film, whatever the title or country.","example":1368337},"allocineId":{"type":"string","pattern":"^\\d{1,12}$","description":"Optional. Every showtime of this Allociné film (allocine.fr/film/fichefilm_gen_cfilm=<id>.html).","example":"1000013045"},"near":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusKm":{"type":"number","exclusiveMinimum":0,"maximum":100,"default":10}},"required":["lat","lng"],"additionalProperties":false,"description":"Optional. Centre point and radius (default 10 km); results carry `distanceKm`.","example":{"lat":45.764,"lng":4.8357,"radiusKm":5}},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Optional. Whole day, in each cinema's local time.","example":"2026-09-25"},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}(?::\\d{2})?)?$","description":"Optional. YYYY-MM-DD or YYYY-MM-DDTHH:MM, in each cinema's local time. Defaults to now in each cinema's time zone.","example":"2026-09-25T18:00"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}(?::\\d{2})?)?$","description":"Optional. YYYY-MM-DD or YYYY-MM-DDTHH:MM, in each cinema's local time.","example":"2026-09-26"},"version":{"type":"string","enum":["VF","VO","VOST","VFST","UNKNOWN"],"example":"VOST","description":"Optional."},"updatedSince":{"type":"string","maxLength":40,"description":"Optional. Incremental sync, as `updated_since` of `GET /v1/showtimes`.","example":"2026-09-16T03:00:00Z"},"include":{"type":"array","items":{"type":"string","enum":["movie","cinema"]},"description":"Optional. Nested objects to embed. Default both; `[]` returns only `movieId` / `cinemaId`.","example":["movie"]},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":50,"example":100,"description":"Optional."},"offset":{"type":"integer","minimum":0,"default":0,"example":0,"description":"Optional."},"cursor":{"type":"string","maxLength":200,"description":"Optional. `meta.nextCursor` of the previous page."}},"additionalProperties":false,"example":{"country":"FR","allocineId":"1000013045","near":{"lat":45.764,"lng":4.8357,"radiusKm":5},"from":"2026-09-25T18:00","include":["movie"],"limit":100}},"MovieList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Movie"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]},"MovieSearch":{"type":"object","properties":{"q":{"type":"string","minLength":1,"description":"Optional. Title search (accent/case-insensitive).","example":"odyssée"},"playing":{"type":"boolean","description":"Optional. Only movies with upcoming showtimes (in `country` when given)."},"country":{"type":"string","enum":["FR","US"],"description":"Optional. Only movies shown in this country.","example":"FR"},"tmdbId":{"type":"integer","exclusiveMinimum":0,"description":"Optional. Every row of this TMDB film.","example":1368337},"allocineId":{"type":"string","pattern":"^\\d{1,12}$","description":"Optional. Every row of this Allociné film.","example":"1000013045"},"updatedSince":{"type":"string","maxLength":40,"description":"Optional. Only movies changed since this ISO 8601 instant.","example":"2026-09-16T03:00:00Z"},"limit":{"type":"integer","minimum":1,"maximum":200,"default":50,"example":50,"description":"Optional."},"offset":{"type":"integer","minimum":0,"default":0,"example":0,"description":"Optional."}},"additionalProperties":false,"example":{"q":"odyssée","playing":true,"country":"FR"}},"UnmatchedMovieList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UnmatchedMovie"}},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"]},"UnmatchedMovie":{"type":"object","properties":{"movie":{"$ref":"#/components/schemas/Movie"},"upcomingShowtimes":{"type":"integer","example":403},"cinemas":{"type":"integer","description":"Active cinemas showing it","example":135}},"required":["movie","upcomingShowtimes","cinemas"]},"MovieShowtimeSearch":{"type":"object","properties":{"country":{"type":"string","enum":["FR","US"],"description":"Optional. Only cinemas of this country. Default: every country.","example":"FR"},"city":{"type":"string","minLength":1,"description":"Optional. Exact city name; `Paris` also matches its arrondissements.","example":"Lyon"},"near":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radiusKm":{"type":"number","exclusiveMinimum":0,"maximum":100,"default":10}},"required":["lat","lng"],"additionalProperties":false,"description":"Optional. Centre point and radius (default 10 km); results carry `distanceKm`.","example":{"lat":45.764,"lng":4.8357,"radiusKm":5}},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Optional. Whole day, in each cinema's local time.","example":"2026-09-25"},"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}(?::\\d{2})?)?$","description":"Optional. YYYY-MM-DD or YYYY-MM-DDTHH:MM, in each cinema's local time. Defaults to now in each cinema's time zone.","example":"2026-09-25T18:00"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}(?::\\d{2})?)?$","description":"Optional. YYYY-MM-DD or YYYY-MM-DDTHH:MM, in each cinema's local time.","example":"2026-09-26"},"version":{"type":"string","enum":["VF","VO","VOST","VFST","UNKNOWN"],"example":"VOST","description":"Optional."},"include":{"type":"array","items":{"type":"string","enum":["movie","cinema"]},"description":"Optional. Nested objects to embed. Default both; `[]` returns only `movieId` / `cinemaId`.","example":["movie"]},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":50,"example":100,"description":"Optional."},"offset":{"type":"integer","minimum":0,"default":0,"example":0,"description":"Optional."},"cursor":{"type":"string","maxLength":200,"description":"Optional. `meta.nextCursor` of the previous page."}},"additionalProperties":false,"example":{"country":"FR","near":{"lat":48.8566,"lng":2.3522,"radiusKm":5},"include":["cinema"]}},"Health":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"version":{"type":"string"}},"required":["ok","version"]}},"parameters":{}},"paths":{"/v1/cinemas":{"get":{"tags":["Cinemas"],"summary":"List cinemas","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"description":"Optional. Exact city name; `Paris` also matches its arrondissements. Example: `Paris`.","name":"city","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Optional. Name contains. Example: `champo`.","name":"q","in":"query"},{"schema":{"type":"string","pattern":"^\\d{2,5}$"},"required":false,"description":"Optional. Postal code (FR) or ZIP code (US) starts with: `75005` for one code, `75` for a whole French department, `100` for a range of US ZIP codes. 2 to 5 digits. Example: `75005`.","name":"zip_code","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"true"},"required":false,"description":"Optional. Default true.","name":"active","in":"query"},{"schema":{"type":"string","enum":["FR","US"]},"required":false,"description":"Optional. Only cinemas of this country (ISO 3166-1 alpha-2). Default: every country. Example: `FR`.","name":"country","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Optional. \"lat,lng\" centre point. Example: `48.8566,2.3522`.","name":"near","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":100},"required":false,"description":"Optional. Radius around `near`, default 10. Example: `5`.","name":"radius_km","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query","description":"Optional. Example: `50`."},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query","description":"Optional. Example: `0`."}],"responses":{"200":{"description":"Cinemas","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CinemaList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access of the account suspended (`account_suspended`), for instance when another account was signed up first from the same connection: one account per client (terms of use, section 2).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this API key (60 requests per minute on the standard plan, 600 on pro; `rate_limited`), or weekly quota of the account exceeded (`weekly_quota_exceeded`, when one is set). Wait `Retry-After` seconds.","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}},"Retry-After":{"description":"Seconds to wait before retrying (end of the current window).","schema":{"type":"integer","example":23}}},"content":{"application/json":{"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded: 60 requests per 60 s for this API key. Retry in 23 s.","details":{"limit":60,"windowSeconds":60,"retryAfterSeconds":23,"plan":"standard"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cinemas/search":{"post":{"tags":["Cinemas"],"summary":"Search cinemas with a JSON body","description":"Same filters and results as `GET /v1/cinemas`, sent as a JSON body (typed values, camelCase names). Read-only.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CinemaSearch"}}}},"responses":{"200":{"description":"Cinemas","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CinemaList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access of the account suspended (`account_suspended`), for instance when another account was signed up first from the same connection: one account per client (terms of use, section 2).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this API key (60 requests per minute on the standard plan, 600 on pro; `rate_limited`), or weekly quota of the account exceeded (`weekly_quota_exceeded`, when one is set). Wait `Retry-After` seconds.","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}},"Retry-After":{"description":"Seconds to wait before retrying (end of the current window).","schema":{"type":"integer","example":23}}},"content":{"application/json":{"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded: 60 requests per 60 s for this API key. Retry in 23 s.","details":{"limit":60,"windowSeconds":60,"retryAfterSeconds":23,"plan":"standard"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cinemas/{id}":{"get":{"tags":["Cinemas"],"summary":"Get a cinema by id or slug","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Cinema `id` or `slug`, as returned by `GET /v1/cinemas` (or `cinemaId` / `cinema.id` of a showtime)","example":"cnc_188341"},"required":true,"description":"Cinema `id` or `slug`, as returned by `GET /v1/cinemas` (or `cinemaId` / `cinema.id` of a showtime)","name":"id","in":"path"}],"responses":{"200":{"description":"Cinema","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cinema"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access of the account suspended (`account_suspended`), for instance when another account was signed up first from the same connection: one account per client (terms of use, section 2).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this API key (60 requests per minute on the standard plan, 600 on pro; `rate_limited`), or weekly quota of the account exceeded (`weekly_quota_exceeded`, when one is set). Wait `Retry-After` seconds.","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}},"Retry-After":{"description":"Seconds to wait before retrying (end of the current window).","schema":{"type":"integer","example":23}}},"content":{"application/json":{"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded: 60 requests per 60 s for this API key. Retry in 23 s.","details":{"limit":60,"windowSeconds":60,"retryAfterSeconds":23,"plan":"standard"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cinemas/{id}/showtimes":{"get":{"tags":["Cinemas","Showtimes"],"summary":"Showtimes of a cinema (defaults to today)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Cinema `id` or `slug`, as returned by `GET /v1/cinemas` (or `cinemaId` / `cinema.id` of a showtime)","example":"cnc_188341"},"required":true,"description":"Cinema `id` or `slug`, as returned by `GET /v1/cinemas` (or `cinemaId` / `cinema.id` of a showtime)","name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"description":"Optional. Whole day, YYYY-MM-DD, in each cinema's local time. Example: `2026-09-15`.","name":"date","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Optional. YYYY-MM-DD or YYYY-MM-DDTHH:MM, in each cinema's local time. Defaults to now in each cinema's time zone. Example: `2026-09-15T18:00`.","name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Optional. YYYY-MM-DD or YYYY-MM-DDTHH:MM, in each cinema's local time. Example: `2026-09-16`.","name":"to","in":"query"},{"schema":{"type":"string","enum":["VF","VO","VOST","VFST","UNKNOWN"]},"required":false,"name":"version","in":"query","description":"Optional. Example: `VOST`."},{"schema":{"type":"string","maxLength":40},"required":false,"description":"Optional. Nested objects to embed, comma-separated: `movie`, `cinema`. Default `movie,cinema`; `include=` (empty) returns only `movieId` / `cinemaId`, for much lighter pages on full imports. Example: `movie`.","name":"include","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":50},"required":false,"description":"Optional. Page size, up to 1000. Example: `1000`.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"description":"Optional. Rows to skip. For deep pages, walk with `cursor` instead. Example: `0`.","name":"offset","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"description":"Optional. `meta.nextCursor` of the previous page. Walks the whole result set in a stable order (startsAt, id); not combinable with `offset` or `near`.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Showtimes","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShowtimeList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access of the account suspended (`account_suspended`), for instance when another account was signed up first from the same connection: one account per client (terms of use, section 2).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this API key (60 requests per minute on the standard plan, 600 on pro; `rate_limited`), or weekly quota of the account exceeded (`weekly_quota_exceeded`, when one is set). Wait `Retry-After` seconds.","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}},"Retry-After":{"description":"Seconds to wait before retrying (end of the current window).","schema":{"type":"integer","example":23}}},"content":{"application/json":{"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded: 60 requests per 60 s for this API key. Retry in 23 s.","details":{"limit":60,"windowSeconds":60,"retryAfterSeconds":23,"plan":"standard"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/cinemas/{id}/showtimes/search":{"post":{"tags":["Cinemas","Showtimes"],"summary":"Showtimes of a cinema with a JSON body (defaults to today)","description":"Same filters and results as `GET /v1/cinemas/{id}/showtimes`, sent as a JSON body (typed values, camelCase names). Read-only.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Cinema `id` or `slug`, as returned by `GET /v1/cinemas` (or `cinemaId` / `cinema.id` of a showtime)","example":"cnc_188341"},"required":true,"description":"Cinema `id` or `slug`, as returned by `GET /v1/cinemas` (or `cinemaId` / `cinema.id` of a showtime)","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CinemaShowtimeSearch"}}}},"responses":{"200":{"description":"Showtimes","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShowtimeList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access of the account suspended (`account_suspended`), for instance when another account was signed up first from the same connection: one account per client (terms of use, section 2).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this API key (60 requests per minute on the standard plan, 600 on pro; `rate_limited`), or weekly quota of the account exceeded (`weekly_quota_exceeded`, when one is set). Wait `Retry-After` seconds.","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}},"Retry-After":{"description":"Seconds to wait before retrying (end of the current window).","schema":{"type":"integer","example":23}}},"content":{"application/json":{"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded: 60 requests per 60 s for this API key. Retry in 23 s.","details":{"limit":60,"windowSeconds":60,"retryAfterSeconds":23,"plan":"standard"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/showtimes":{"get":{"tags":["Showtimes"],"summary":"Search showtimes (defaults to upcoming from now)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"description":"Optional. Exact city name; `Paris` also matches its arrondissements. Example: `Lyon`.","name":"city","in":"query"},{"schema":{"type":"string"},"required":false,"name":"movie_id","in":"query","description":"Optional."},{"schema":{"type":"integer","exclusiveMinimum":0},"required":false,"description":"Optional. The Movie Database id: every showtime of this film, whatever the title published by each cinema or the country. Example: `1368337`.","name":"tmdb_id","in":"query"},{"schema":{"type":"string","pattern":"^\\d{1,12}$"},"required":false,"description":"Optional. Allociné film id, as in allocine.fr/film/fichefilm_gen_cfilm=<id>.html: every showtime of this film (also those read from other sources, once the film is matched on TMDB). Example: `1000013045`.","name":"allocine_id","in":"query"},{"schema":{"type":"string","enum":["FR","US"]},"required":false,"description":"Optional. Only cinemas of this country (ISO 3166-1 alpha-2). Default: every country. Example: `FR`.","name":"country","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Optional. \"lat,lng\" centre point. Example: `48.8566,2.3522`.","name":"near","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":100},"required":false,"description":"Optional. Radius around `near`, default 10. Example: `5`.","name":"radius_km","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Optional. Whole day, YYYY-MM-DD, in each cinema's local time. Example: `2026-09-15`.","name":"date","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Optional. YYYY-MM-DD or YYYY-MM-DDTHH:MM, in each cinema's local time. Defaults to now in each cinema's time zone. Example: `2026-09-15T18:00`.","name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Optional. YYYY-MM-DD or YYYY-MM-DDTHH:MM, in each cinema's local time. Example: `2026-09-16`.","name":"to","in":"query"},{"schema":{"type":"string","enum":["VF","VO","VOST","VFST","UNKNOWN"]},"required":false,"name":"version","in":"query","description":"Optional. Example: `VOST`."},{"schema":{"type":"string","maxLength":40},"required":false,"description":"Optional. Incremental sync: only showtimes inserted, changed or removed since this ISO 8601 instant, removed ones included (`removedAt` set), ordered by (updatedAt, id). Pass `meta.syncedAt` of the first page of your previous walk. Tombstones are kept 30 days: sync at least that often, or do a full walk. Example: `2026-09-16T03:00:00Z`.","name":"updated_since","in":"query"},{"schema":{"type":"string","maxLength":40},"required":false,"description":"Optional. Nested objects to embed, comma-separated: `movie`, `cinema`. Default `movie,cinema`; `include=` (empty) returns only `movieId` / `cinemaId`, for much lighter pages on full imports. Example: `movie`.","name":"include","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":50},"required":false,"description":"Optional. Page size, up to 1000. Example: `1000`.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"description":"Optional. Rows to skip. For deep pages, walk with `cursor` instead. Example: `0`.","name":"offset","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"description":"Optional. `meta.nextCursor` of the previous page. Walks the whole result set in a stable order (startsAt, id); not combinable with `offset` or `near`.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Showtimes","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShowtimeList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access of the account suspended (`account_suspended`), for instance when another account was signed up first from the same connection: one account per client (terms of use, section 2).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this API key (60 requests per minute on the standard plan, 600 on pro; `rate_limited`), or weekly quota of the account exceeded (`weekly_quota_exceeded`, when one is set). Wait `Retry-After` seconds.","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}},"Retry-After":{"description":"Seconds to wait before retrying (end of the current window).","schema":{"type":"integer","example":23}}},"content":{"application/json":{"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded: 60 requests per 60 s for this API key. Retry in 23 s.","details":{"limit":60,"windowSeconds":60,"retryAfterSeconds":23,"plan":"standard"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/showtimes/search":{"post":{"tags":["Showtimes"],"summary":"Search showtimes with a JSON body","description":"Same filters and results as `GET /v1/showtimes`, sent as a JSON body with typed values and camelCase names instead of a long query string. Read-only: nothing is created.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShowtimeSearch"}}}},"responses":{"200":{"description":"Showtimes","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShowtimeList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access of the account suspended (`account_suspended`), for instance when another account was signed up first from the same connection: one account per client (terms of use, section 2).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this API key (60 requests per minute on the standard plan, 600 on pro; `rate_limited`), or weekly quota of the account exceeded (`weekly_quota_exceeded`, when one is set). Wait `Retry-After` seconds.","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}},"Retry-After":{"description":"Seconds to wait before retrying (end of the current window).","schema":{"type":"integer","example":23}}},"content":{"application/json":{"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded: 60 requests per 60 s for this API key. Retry in 23 s.","details":{"limit":60,"windowSeconds":60,"retryAfterSeconds":23,"plan":"standard"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/movies":{"get":{"tags":["Movies"],"summary":"List movies","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"description":"Optional. Title search (accent/case-insensitive). Example: `dune`.","name":"q","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"description":"Optional. Only movies with upcoming showtimes (in `country` when given).","name":"playing","in":"query"},{"schema":{"type":"string","maxLength":40},"required":false,"description":"Optional. Only movies changed since this ISO 8601 instant (TMDB match, alias, metadata). Example: `2026-09-16T03:00:00Z`.","name":"updated_since","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0},"required":false,"description":"Optional. The Movie Database id: every showtime of this film, whatever the title published by each cinema or the country. Example: `1368337`.","name":"tmdb_id","in":"query"},{"schema":{"type":"string","pattern":"^\\d{1,12}$"},"required":false,"description":"Optional. Allociné film id, as in allocine.fr/film/fichefilm_gen_cfilm=<id>.html: every showtime of this film (also those read from other sources, once the film is matched on TMDB). Example: `1000013045`.","name":"allocine_id","in":"query"},{"schema":{"type":"string","enum":["FR","US"]},"required":false,"description":"Optional. Only cinemas of this country (ISO 3166-1 alpha-2). Default: every country. Example: `FR`.","name":"country","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query","description":"Optional. Example: `50`."},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query","description":"Optional. Example: `0`."}],"responses":{"200":{"description":"Movies","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MovieList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access of the account suspended (`account_suspended`), for instance when another account was signed up first from the same connection: one account per client (terms of use, section 2).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this API key (60 requests per minute on the standard plan, 600 on pro; `rate_limited`), or weekly quota of the account exceeded (`weekly_quota_exceeded`, when one is set). Wait `Retry-After` seconds.","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}},"Retry-After":{"description":"Seconds to wait before retrying (end of the current window).","schema":{"type":"integer","example":23}}},"content":{"application/json":{"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded: 60 requests per 60 s for this API key. Retry in 23 s.","details":{"limit":60,"windowSeconds":60,"retryAfterSeconds":23,"plan":"standard"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/movies/search":{"post":{"tags":["Movies"],"summary":"Search movies with a JSON body","description":"Same filters and results as `GET /v1/movies`, sent as a JSON body (typed values, camelCase names). Read-only.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MovieSearch"}}}},"responses":{"200":{"description":"Movies","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MovieList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access of the account suspended (`account_suspended`), for instance when another account was signed up first from the same connection: one account per client (terms of use, section 2).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this API key (60 requests per minute on the standard plan, 600 on pro; `rate_limited`), or weekly quota of the account exceeded (`weekly_quota_exceeded`, when one is set). Wait `Retry-After` seconds.","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}},"Retry-After":{"description":"Seconds to wait before retrying (end of the current window).","schema":{"type":"integer","example":23}}},"content":{"application/json":{"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded: 60 requests per 60 s for this API key. Retry in 23 s.","details":{"limit":60,"windowSeconds":60,"retryAfterSeconds":23,"plan":"standard"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/movies/unmatched":{"get":{"tags":["Movies"],"summary":"Movies showing without a TMDB match, most programmed first","description":"Upcoming movies whose `tmdbId` is still null, ordered by number of upcoming showtimes: lets you watch the TMDB matching over time.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query","description":"Optional. Example: `50`."},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query","description":"Optional. Example: `0`."}],"responses":{"200":{"description":"Unmatched movies","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnmatchedMovieList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access of the account suspended (`account_suspended`), for instance when another account was signed up first from the same connection: one account per client (terms of use, section 2).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this API key (60 requests per minute on the standard plan, 600 on pro; `rate_limited`), or weekly quota of the account exceeded (`weekly_quota_exceeded`, when one is set). Wait `Retry-After` seconds.","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}},"Retry-After":{"description":"Seconds to wait before retrying (end of the current window).","schema":{"type":"integer","example":23}}},"content":{"application/json":{"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded: 60 requests per 60 s for this API key. Retry in 23 s.","details":{"limit":60,"windowSeconds":60,"retryAfterSeconds":23,"plan":"standard"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/movies/{id}":{"get":{"tags":["Movies"],"summary":"Get a movie","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Movie `id` (ours), as returned by `GET /v1/movies?q=…`, `GET /v1/movies?tmdb_id=…` / `?allocine_id=…`, or `movieId` of a showtime. A film can have several ids (one per country, or per published title until it is matched on TMDB): to get every showtime of a film from its TMDB or Allociné id, prefer `GET /v1/showtimes?tmdb_id=…` / `?allocine_id=…`","example":"7482dc62-6c35-4c0a-b894-2d2bcf04296f"},"required":true,"description":"Movie `id` (ours), as returned by `GET /v1/movies?q=…`, `GET /v1/movies?tmdb_id=…` / `?allocine_id=…`, or `movieId` of a showtime. A film can have several ids (one per country, or per published title until it is matched on TMDB): to get every showtime of a film from its TMDB or Allociné id, prefer `GET /v1/showtimes?tmdb_id=…` / `?allocine_id=…`","name":"id","in":"path"}],"responses":{"200":{"description":"Movie","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Movie"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access of the account suspended (`account_suspended`), for instance when another account was signed up first from the same connection: one account per client (terms of use, section 2).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this API key (60 requests per minute on the standard plan, 600 on pro; `rate_limited`), or weekly quota of the account exceeded (`weekly_quota_exceeded`, when one is set). Wait `Retry-After` seconds.","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}},"Retry-After":{"description":"Seconds to wait before retrying (end of the current window).","schema":{"type":"integer","example":23}}},"content":{"application/json":{"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded: 60 requests per 60 s for this API key. Retry in 23 s.","details":{"limit":60,"windowSeconds":60,"retryAfterSeconds":23,"plan":"standard"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/movies/{id}/showtimes":{"get":{"tags":["Movies","Showtimes"],"summary":"Showtimes of a movie (defaults to upcoming from now)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Movie `id` (ours), as returned by `GET /v1/movies?q=…`, `GET /v1/movies?tmdb_id=…` / `?allocine_id=…`, or `movieId` of a showtime. A film can have several ids (one per country, or per published title until it is matched on TMDB): to get every showtime of a film from its TMDB or Allociné id, prefer `GET /v1/showtimes?tmdb_id=…` / `?allocine_id=…`","example":"7482dc62-6c35-4c0a-b894-2d2bcf04296f"},"required":true,"description":"Movie `id` (ours), as returned by `GET /v1/movies?q=…`, `GET /v1/movies?tmdb_id=…` / `?allocine_id=…`, or `movieId` of a showtime. A film can have several ids (one per country, or per published title until it is matched on TMDB): to get every showtime of a film from its TMDB or Allociné id, prefer `GET /v1/showtimes?tmdb_id=…` / `?allocine_id=…`","name":"id","in":"path"},{"schema":{"type":"string"},"required":false,"description":"Optional. Exact city name; `Paris` also matches its arrondissements. Example: `Paris`.","name":"city","in":"query"},{"schema":{"type":"string","enum":["FR","US"]},"required":false,"description":"Optional. Only cinemas of this country (ISO 3166-1 alpha-2). Default: every country. Example: `FR`.","name":"country","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Optional. \"lat,lng\" centre point. Example: `48.8566,2.3522`.","name":"near","in":"query"},{"schema":{"type":"number","exclusiveMinimum":0,"maximum":100},"required":false,"description":"Optional. Radius around `near`, default 10. Example: `5`.","name":"radius_km","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Optional. Whole day, YYYY-MM-DD, in each cinema's local time. Example: `2026-09-15`.","name":"date","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Optional. YYYY-MM-DD or YYYY-MM-DDTHH:MM, in each cinema's local time. Defaults to now in each cinema's time zone. Example: `2026-09-15T18:00`.","name":"from","in":"query"},{"schema":{"type":"string"},"required":false,"description":"Optional. YYYY-MM-DD or YYYY-MM-DDTHH:MM, in each cinema's local time. Example: `2026-09-16`.","name":"to","in":"query"},{"schema":{"type":"string","enum":["VF","VO","VOST","VFST","UNKNOWN"]},"required":false,"name":"version","in":"query","description":"Optional. Example: `VOST`."},{"schema":{"type":"string","maxLength":40},"required":false,"description":"Optional. Nested objects to embed, comma-separated: `movie`, `cinema`. Default `movie,cinema`; `include=` (empty) returns only `movieId` / `cinemaId`, for much lighter pages on full imports. Example: `movie`.","name":"include","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"default":50},"required":false,"description":"Optional. Page size, up to 1000. Example: `1000`.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"description":"Optional. Rows to skip. For deep pages, walk with `cursor` instead. Example: `0`.","name":"offset","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"description":"Optional. `meta.nextCursor` of the previous page. Walks the whole result set in a stable order (startsAt, id); not combinable with `offset` or `near`.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Showtimes","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShowtimeList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access of the account suspended (`account_suspended`), for instance when another account was signed up first from the same connection: one account per client (terms of use, section 2).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this API key (60 requests per minute on the standard plan, 600 on pro; `rate_limited`), or weekly quota of the account exceeded (`weekly_quota_exceeded`, when one is set). Wait `Retry-After` seconds.","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}},"Retry-After":{"description":"Seconds to wait before retrying (end of the current window).","schema":{"type":"integer","example":23}}},"content":{"application/json":{"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded: 60 requests per 60 s for this API key. Retry in 23 s.","details":{"limit":60,"windowSeconds":60,"retryAfterSeconds":23,"plan":"standard"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/movies/{id}/showtimes/search":{"post":{"tags":["Movies","Showtimes"],"summary":"Showtimes of a movie with a JSON body (defaults to upcoming from now)","description":"Same filters and results as `GET /v1/movies/{id}/showtimes`, sent as a JSON body (typed values, camelCase names). Read-only.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Movie `id` (ours), as returned by `GET /v1/movies?q=…`, `GET /v1/movies?tmdb_id=…` / `?allocine_id=…`, or `movieId` of a showtime. A film can have several ids (one per country, or per published title until it is matched on TMDB): to get every showtime of a film from its TMDB or Allociné id, prefer `GET /v1/showtimes?tmdb_id=…` / `?allocine_id=…`","example":"7482dc62-6c35-4c0a-b894-2d2bcf04296f"},"required":true,"description":"Movie `id` (ours), as returned by `GET /v1/movies?q=…`, `GET /v1/movies?tmdb_id=…` / `?allocine_id=…`, or `movieId` of a showtime. A film can have several ids (one per country, or per published title until it is matched on TMDB): to get every showtime of a film from its TMDB or Allociné id, prefer `GET /v1/showtimes?tmdb_id=…` / `?allocine_id=…`","name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MovieShowtimeSearch"}}}},"responses":{"200":{"description":"Showtimes","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShowtimeList"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access of the account suspended (`account_suspended`), for instance when another account was signed up first from the same connection: one account per client (terms of use, section 2).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded for this API key (60 requests per minute on the standard plan, 600 on pro; `rate_limited`), or weekly quota of the account exceeded (`weekly_quota_exceeded`, when one is set). Wait `Retry-After` seconds.","headers":{"RateLimit-Policy":{"description":"Quota of the API key: `\"standard\";q=60;w=60` (60 requests per 60 s) or `\"pro\";q=600;w=60`.","schema":{"type":"string","example":"\"standard\";q=60;w=60"}},"RateLimit":{"description":"Requests left (`r`) and seconds until the window resets (`t`).","schema":{"type":"string","example":"\"standard\";r=41;t=23"}},"X-RateLimit-Limit":{"description":"Requests allowed per 60-second window for this API key.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests left in the current window, this one included.","schema":{"type":"integer","example":41}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":23}},"X-Weekly-Quota-Limit":{"description":"Only when your account has a weekly quota: requests allowed per week (Monday 00:00 UTC → Sunday), all your API keys together.","schema":{"type":"integer","example":10000}},"X-Weekly-Quota-Remaining":{"description":"Only with a weekly quota: requests left this week, this one included.","schema":{"type":"integer","example":8412}},"X-Weekly-Quota-Reset":{"description":"Only with a weekly quota: seconds until Monday 00:00 UTC.","schema":{"type":"integer","example":302400}},"Retry-After":{"description":"Seconds to wait before retrying (end of the current window).","schema":{"type":"integer","example":23}}},"content":{"application/json":{"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded: 60 requests per 60 s for this API key. Retry in 23 s.","details":{"limit":60,"windowSeconds":60,"retryAfterSeconds":23,"plan":"standard"}}},"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/health":{"get":{"tags":["Meta"],"summary":"Liveness check","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}}},"webhooks":{}}