Skip to main content
POST
/
search
/
file
curl -X POST -H "User-Agent: my-app-name/1.0" \ -H "Content-Type: application/json" \ -d '{"file":"Stranger.Things.S01E03.1080p.WEB.x264.mkv"}' \ "https://api.simkl.com/search/file?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
{ "type": "episode", "episode": { "title": "Chapter Three: Holly, Jolly", "season": 1, "episode": 3, "multipart": false, "ids": { "simkl": 1865356 } }, "show": { "title": "Stranger Things", "year": 2016, "ids": { "simkl": 548312, "tvdbslug": "stranger-things", "tmdbtv": "66732", "imdb": "tt4574334", "trakttvslug": "stranger-things", "tvdb": "305288" } } }

Documentation Index

Fetch the complete documentation index at: https://api.simkl.org/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
client_id
string
query
default:YOUR_CLIENT_ID
required

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

​
User-Agent
string
required

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

​
client_id
string
required

Your client_id from your Simkl developer settings. Required on every request.

​
app-name
string
required

Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.

​
app-version
string
required

Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.

Body

application/json
​
file
string
required

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.

Examples:

"Were.The.Fugawis.S01E01E02.WS.DSR.x264-NY2.mkv"

"/series/The Office/Season 4/The Office [401] Fun Run.avi"

​
part
integer

For multi-part filenames (e.g. S01E01E02 = two episodes in one file), the 1-based part index you want metadata for. Default 1.

Required range: x >= 1
Example:

1

​
hash
string

Optional file hash for additional disambiguation. Pass through if your scrobble integration computes one; safe to omit.

​
process
string

Optional pre-processing hint for the filename parser. Most clients can omit.

Response

Episode match · object | Show match · object | Movie match · object | any[] | null

OK

Filename matched a TV/anime episode. Carries both the show (parent) and the specific matched episode.

​
type
enum<string>
required

Discriminator — pinned to "episode" for this variant.

Available options:
episode
​
episode
object
required

Matched episode metadata. Present only on type: "episode" responses.

​
show
object
required

Show metadata (TV or anime).