Find an item by file name
Identify a single video file the user just opened. Pass one filename and Simkl returns the matched movie, or the show + the specific episode the filename names. Built for desktop scrobblers and player overlays that need to recognize what the user is currently watching — apps that don’t already have parsed metadata from a media server.
The server normalizes the filename (release tags, resolution, codec markers, group names) and matches it against the Simkl catalog — so messy real-world filenames like Stranger.Things.S01E03.1080p.WEB.x264-GROUP.mkv work fine.
Body fields
| Field | Required | Notes |
|---|---|---|
file | yes | The file name or /path/to/folder/file.mkv. The alias File (capital F) is also accepted for legacy clients. |
part | no | 1-based part index for multi-part files (S01E01E02.mkv is two episodes — pass part: 2 for the second). Default 1. |
process | no | Optional pre-processing hint forwarded to the parser. Most clients can omit. |
hash | no | Optional file hash for additional disambiguation. |
Response shape — discriminated by type
The top-level type field tells you which variant you got:
type | When | Top-level blocks present |
|---|---|---|
"movie" | Filename matched a movie | movie |
"show" | Filename matched a TV/anime show but no specific episode | show |
"episode" | Filename matched a TV/anime episode | show + episode |
Movies and shows carry an ids block populated by Simkl’s link database — typically simkl + several external IDs (imdb, tmdb/tmdbtv, tvdb, anime sources like mal / anidb / anilist / kitsu / crunchyroll, plus slugs for Letterboxd / Trakt / TVDB). Anime episodes return as type: "episode" with the standard show+episode blocks — the file parser doesn’t distinguish anime from TV at the top level.
Edge responses (status 200)
| Body | Meaning |
|---|---|
null | Empty or malformed request body — no file field present. |
[] | Parser ran but couldn’t match the filename to anything in the database. |
Both are 200 — there’s no 404 or 400 for these cases. Treat both as “no match” in client code.
Authorizations
Preferred form: your client_id as a URL query parameter on every request. Self-describing in logs and curl commands. See Headers and required parameters.
Headers
Body
Filename or path (with folders) to match against the Simkl catalog. Both bare filenames and /path/to/show/SxxEyy.mkv style paths are accepted. The alias File (capital F) is also accepted for legacy clients.
"Were.The.Fugawis.S01E01E02.WS.DSR.x264-NY2.mkv"
"/series/The Office/Season 4/The Office [401] Fun Run.avi"
Response
OK
Filename matched a TV/anime episode. Carries both the show (parent) and the specific matched episode.