Crtik Connect lets an app work with a member's Crtik account: read Crtik's scores for a title, see what the member has rated and watched, and record what they finish and rate as they do it.
It covers movies and TV, including anime. By using it you agree to the Developer Terms.
Start
Sign in to Crtik, open Account settings, choose Apps, and register your app under Your apps. A member can register up to 5 apps. Registration gives you an app key that starts with crtik_app_.
An app's name cannot contain Crtik, Official or Verified, and it cannot match another app's name (names are compared without case, accents, spaces or punctuation).
The app key names your app. It is public, so it is safe to ship inside a mobile or browser app. Send it in the X-Crtik-App-Key header on every request, including the sign-in calls.
Sign in
The person approves your app on a Crtik page, with a short code. Your app never sees their password. There are three steps.
Call POST /api/v1/device/code with the permissions you want. The scopes must be a non-empty list of distinct permissions.
curl -X POST https://crtik.com/api/v1/device/code \
-H "X-Crtik-App-Key: crtik_app_…" \
-H "Content-Type: application/json" \
-d '{"scopes": ["activity:write", "activity:read"]}'{
"device_code": "…",
"user_code": "BCDF-GHJK",
"verification_uri": "https://crtik.com/connect",
"verification_uri_complete": "https://crtik.com/connect?code=BCDF-GHJK",
"expires_in": 900,
"interval": 5
}On screen, show user_code and a QR code of verification_uri_complete. Someone on the same device can follow the link instead. The person signs in to Crtik, checks that the code matches, and approves or denies your app. A code can be used once and expires after 15 minutes (expires_in, in seconds). Keep device_code to yourself; it is for step 3 only.
A member can have at most 25 connected apps. At the limit their approval does not go through, and your app keeps seeing pending until the code expires.
Every interval seconds, call POST /api/v1/device/token with the device_code until the status is no longer pending.
curl -X POST https://crtik.com/api/v1/device/token \
-H "X-Crtik-App-Key: crtik_app_…" \
-H "Content-Type: application/json" \
-d '{"device_code": "…"}'| status | What to do |
|---|---|
pending | The person has not answered yet. Poll again after interval seconds. |
slow_down | You polled sooner than interval. Wait at least that long before the next poll. |
approved | The response carries access_token, token_type (Bearer) and the scopes the person granted. Stop polling. |
denied | The person said no. Stop, and tell them the connection was not made. |
expired | The code ran out or was already used. Start again at step 1. |
{
"status": "approved",
"access_token": "crtik_at_…",
"token_type": "Bearer",
"scopes": ["activity:write", "activity:read"]
}The token is shown once and Crtik stores only a hash of it, so it cannot be shown again. Store it securely (the system keychain on a phone or TV, never in a log or a URL), and send it as Authorization: Bearer crtik_at_…. There is no refresh. A token ends when the person disconnects the app, when the app is disabled or deleted, when their account is deleted, or after twelve months unused. After that, every call with it answers invalid_token and the person signs in again.
Identity
GET /api/v1/me tells your app which Crtik account connected it, so you can show “Connected as @bob”. It needs a token and no particular permission: every connected app can call it.
curl https://crtik.com/api/v1/me \
-H "X-Crtik-App-Key: crtik_app_…" \
-H "Authorization: Bearer crtik_at_…"{
"user": {
"username": "bob",
"display_name": "Bob",
"avatar_url": "https://…",
"url": "https://crtik.com/u/bob"
},
"app": { "name": "Living Room TV" },
"scopes": ["activity:write", "activity:read"]
}Any of username, display_name, avatar_url and url can be null: a member may not have set a display name or picture, and url is null when there is no username. scopes lists the permissions this token holds. The response never includes an email address or anything about another member.
Access
The person sees these on the approval page. Ask only for what your app needs.
| Permission | Allows |
|---|---|
activity:write | Record that the person finished a movie or episode, and that they rated a title. |
activity:read | Read the person's own rating and watched state for a title. |
Read
GET /api/v1/titles returns Crtik's scores for a movie, a show, a season or an episode. Name the title with either tmdb_id and type, or imdb_id.
| Parameter | Meaning |
|---|---|
tmdb_id | The TMDB id of the movie or show. Needs type. |
type | movie or tv. Anime is tv. |
imdb_id | An IMDb id such as tt0133093, instead of tmdb_id and type. Send one or the other, not both. |
season | A season number of a show, 0 to 999. Crtik does not add specials (season 0): one it does not already hold answers title_not_found. |
episode | An episode number, 1 to 9999. Needs season. |
curl "https://crtik.com/api/v1/titles?tmdb_id=603&type=movie" \
-H "X-Crtik-App-Key: crtik_app_…" \
-H "Authorization: Bearer crtik_at_…"{
"title": {
"kind": "movie",
"name": "The Matrix",
"tmdb_id": "603",
"imdb_id": "tt0133093",
"season": null,
"episode": null,
"url": "https://crtik.com/movies/the-matrix"
},
"scores": {
"consensus": 8.1,
"consensus_sources": 5,
"consensus_source_names": ["Crtik", "IMDb", "Letterboxd", "Metacritic", "Rotten Tomatoes"],
"crtik_rating": 8.4,
"crtik_review_count": 112,
"must_play": "gold"
},
"viewer": {
"rating": 9,
"watched": true,
"watched_episodes": []
}
}| Field | Meaning |
|---|---|
title.kind | movie, tv, season or episode. name is always the movie's or show's name, and tmdb_id its TMDB id. imdb_id is null when Crtik has none. season and episode are null when they do not apply. |
title.url | The title's page on Crtik. Link Crtik scores to it. |
scores.consensus | Crtik's Consensus, from 0 to 10, or null. It is null when fewer than two sources count toward it. |
scores.consensus_sources | How many sources the stored Consensus counts. This can be 1 or more while consensus is null. |
scores.consensus_source_names | The names of those sources, or null. It can be null, or shorter than consensus_sources, because a source an operator has hidden is not named while it still counts. Never treat its length as the count. |
scores.crtik_rating | The average of Crtik members' ratings, from 0 to 10, or null. |
scores.crtik_review_count | How many Crtik ratings sit behind that average. |
scores.must_play | The title's Must Watch honour: gold, silver or bronze, or null. |
viewer | The person's own rating (or null), whether they have watched it, and the watched_episodes they have seen, as season and episode pairs. |
You can call this without a token, with just the app key. You then get the public answer and no viewer. viewer appears only when the request carries a token that holds activity:read.
A title Crtik does not hold answers 404 title_not_found, which means “not in Crtik yet”. Reads never add a title, with or without a token: Crtik only looks in what it already holds, so the title answers title_not_found until someone records activity for it.
Write
POST /api/v1/activity records something the person just did in your app. It needs a token that holds activity:write. Send a JSON body:
| Field | Meaning |
|---|---|
event | Required. finished or rated. |
tmdb_id, type, imdb_id, season, episode | The title, named as in the table above. |
rating | Required for rated, a number from 1 to 10 in half steps (7.5 is allowed, 7.3 is not). |
review | Optional text with a rated event, up to 5000 characters. |
spoiler | Optional true or false with a rated event. An app can mark a review as a spoiler and cannot clear the mark. |
occurred_at | Optional. When it happened, as an ISO 8601 date-time with a timezone, such as 2026-12-02T21:30:00-05:00. At most 7 days back and never in the future. Left out, it means now. |
| Event | Accepts | Effect |
|---|---|---|
finished | A movie, or an episode of a show. | Marks it watched. A whole show or a season answers 422 unsupported_target; finish its episodes instead. rating, review and spoiler are refused with this event. |
rated | A movie, a show, a season or an episode. | Saves the person's rating as a review. The latest rating wins. |
Review text is optional. It is saved only when the person has no review text for that title yet; an app never overwrites text. The response's text_saved tells you whether yours was kept. The rating is still recorded either way. Reviews open on release day, so rating an unreleased title answers 409 not_released.
curl -X POST https://crtik.com/api/v1/activity \
-H "X-Crtik-App-Key: crtik_app_…" \
-H "Authorization: Bearer crtik_at_…" \
-H "Content-Type: application/json" \
-d '{
"event": "rated",
"tmdb_id": 603,
"type": "movie",
"rating": 9,
"review": "Still holds up.",
"spoiler": false,
"occurred_at": "2026-12-02T21:30:00-05:00"
}'{
"result": "recorded",
"title": {
"kind": "movie",
"name": "The Matrix",
"tmdb_id": "603",
"imdb_id": "tt0133093",
"season": null,
"episode": null,
"url": "https://crtik.com/movies/the-matrix"
},
"review": { "rating": 9, "created": true, "text_saved": true }
}result is recorded or, for a finished event that changed nothing, unchanged. For finished, review is null. In review, created says whether this was the person's first rating of the title.
This is for live activity only. Send an event when the person finishes or rates something in your app. Do not upload a person's history through it; the Developer Terms forbid that.
End
DELETE /api/v1/connection with the token ends it. The answer is 204 with no body. Call it when the person signs out of your app or removes Crtik from it. They can also disconnect your app from their Crtik account settings.
curl -X DELETE https://crtik.com/api/v1/connection \
-H "X-Crtik-App-Key: crtik_app_…" \
-H "Authorization: Bearer crtik_at_…"Limits
| Call | Limit | Requests |
|---|---|---|
| Writes | per access token, per minute | 30 |
| Writes | per access token, per day | 200 |
| Reads with a token | per access token, per minute | 120 |
| Reads without a token | per app, per minute | 600 |
| Reads without a token | per IP address, per minute | 60 |
| Starting a sign-in | per app, per minute | 60 |
| Starting a sign-in | per IP address, per minute | 10 |
| Polling for the token | per app, per minute | 3000 |
| Polling for the token | per IP address, per minute | 120 |
Over a limit, the answer is 429 with the code rate_limited and a retry-after header holding the seconds to wait. The daily write limit answers daily_limit, without that header. A request body can be at most 16 KB.
HTTP/1.1 429 Too Many Requests
retry-after: 12
content-type: application/json
{ "error": { "code": "rate_limited", "message": "Too many requests. Try again later." } }Errors
Every error has the same shape. Act on code, which is stable. The message is for people and can change.
{ "error": { "code": "invalid_rating", "message": "rating must be a number from 1 to 10 in half steps." } }| code | HTTP status | Meaning |
|---|---|---|
not_available | 404 | The API is not available. |
not_found | 404 | There is no endpoint at that path. Check the address against this page. |
invalid_request | 400 | A parameter or body field is missing or malformed. The message names it. A request the database refuses, such as one for a member who has not finished setting up a profile, answers 422 with this code. |
request_too_large | 413 | The request body is over 16 KB. |
invalid_app | 401 | The app key header is missing, malformed or unknown. |
app_disabled | 403 | The app has been disabled. Every call answers this, including a sign-in poll. |
invalid_token | 401 | The access token is missing, malformed, unknown, expired or ended. A malformed Authorization header is this error even on a route where the token is optional. |
insufficient_permission | 403 | The token does not hold the permission this call needs. |
title_not_found | 404 | This title is not in Crtik yet. |
unsupported_target | 422 | That event does not apply to that title. |
invalid_rating | 422 | The rating is missing, not a number, or not from 1 to 10 in half steps. |
invalid_review | 422 | The review is not text, or it is too long. |
invalid_date | 422 | occurred_at is malformed, in the future, or too far back. |
not_released | 409 | Reviews open on release day. |
review_hidden | 409 | A moderator has hidden this member's review of the title, so its rating cannot be changed through the API. Nothing was recorded. A finished event for the same title still works. |
rate_limited | 429 | Too many requests. Wait for the number of seconds in the retry-after header. |
daily_limit | 429 | This connection has reached its daily write limit. It has no retry-after header; try again tomorrow. |
temporarily_unavailable | 503 | Something went wrong on our side, or a lookup failed. Try again shortly. |
A present but malformed Authorization header is 401 invalid_token even on GET /api/v1/titles, where the token is optional. Leave the header out to read without a token.
Browsers
The API allows requests from any origin and answers preflight requests, so a web app can call it directly. Send no cookies: the API never reads them, and a Crtik login in the browser gives your app no access. Remember that an access token in a web page is readable by that page's scripts.
Brand
Wherever your app shows a Crtik score or rating control, label it as Crtik. Show scores as the API gives them, and link each one to the title's url. The names, labels, colours and logo to use are in the brand guidelines for connected apps.
Keep Crtik scores for at most 24 hours, then read them again. Do not copy them in bulk or build a database from them. The rules are in the Developer Terms.