client_id only — no user token required — and return Standard Media Objects.
Never call search before scrobbling or marking something watched.This is the most common wasted request we see. Apps look the title up first to get a Simkl ID, then send that ID to the write endpoint. The lookup is unnecessary. Every write endpoint resolves the item itself, from whatever you already have:Pass any combination of IDs, plus
title and year as fallbacks, in the same request that records the watch. Simkl matches it server-side. A Simkl ID is never required.That applies to all of them: /scrobble/*, POST /sync/history, POST /sync/add-to-list, and POST /sync/ratings.Searching first doubles your request count for no benefit, burns rate limit you’ll want later, and picks the wrong title whenever the search ranking disagrees with your IDs. One call, not two.Search is for when you have no usable IDs at all — a title the user typed, a file name, or a random pick.Got an external ID and need the full record? Still don’t search — use
/redirect to resolve it to a Simkl ID, then fetch from /movies/{id}, /tv/{id}, or /anime/{id} (Cloudflare-cached by Simkl ID, much cheaper for repeat lookups). Search endpoints are for cases where you only have a title string, a file name, or want a random pick.By text
GET /search/{type} — search by title.By file
POST /search/file — identify content from a file name.Random
POST /search/random — pick a random item.