> ## 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.

# About Search

> Look up items by ID, by title, by file name, or pull a random item.

The Search API lets you find items in Simkl's catalog. All endpoints accept a `client_id` only — no user `token` required — and return [Standard Media Objects](/conventions/standard-media-objects).

<a id="never-search-before-a-write" />

<Danger>
  **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:

  ```json theme={"theme":{"light":"github-light","dark":"vesper"}}
  {
    "movie": {
      "title": "Dune: Part Two",
      "year": 2024,
      "ids": { "imdb": "tt15239678", "tmdb": "693134" }
    }
  }
  ```

  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/*`](/api-reference/scrobble), [`POST /sync/history`](/api-reference/simkl/add-to-history), [`POST /sync/add-to-list`](/api-reference/simkl/add-to-list), and [`POST /sync/ratings`](/api-reference/simkl/add-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.
</Danger>

<Note>
  **Got an external ID and need the full record?** Still don't search — use [`/redirect`](/api-reference/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.
</Note>

| Endpoint | What it does |
| - | - |
| `GET /search/{type}` | Free-text search across `movie`, `tv`, or `anime`. |
| `POST /search/file` | Identify a movie or episode from a file name (great for media servers). |
| `POST /search/random` | Pick a random item, optionally filtered by genre, year, rating, etc. |

<CardGroup cols={3}>
  <Card title="By text" icon="font" href="/api-reference/simkl/search-by-text">
    `GET /search/{type}` — search by title.
  </Card>

  <Card title="By file" icon="file" href="/api-reference/simkl/search-by-file">
    `POST /search/file` — identify content from a file name.
  </Card>

  <Card title="Random" icon="shuffle" href="/api-reference/simkl/search-random">
    `POST /search/random` — pick a random item.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.