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
Descriptive identifier for your app, ideally name/version. Examples: PlexMediaServer/1.43.1.10540, kodi-simkl/0.9.2, MyApp/2.4.1 (https://myapp.com).
Query Parameters
Your client_id from your Simkl developer settings. Required on every request.
Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.
Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.
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"
For multi-part filenames (e.g. S01E01E02 = two episodes in one file), the 1-based part index you want metadata for. Default 1.
x >= 11
Optional file hash for additional disambiguation. Pass through if your scrobble integration computes one; safe to omit.
Optional pre-processing hint for the filename parser. Most clients can omit.
Response
OK
Filename matched a TV/anime episode. Carries both the show (parent) and the specific matched episode.