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

# Search and discover

> Find movies, shows, and anime by ID, text query, file name, or randomly.

Pick the right entry point for your situation — searching by user-typed text, by filename, by external ID, or just browsing the catalog.

<CardGroup cols={2}>
  <Card title="By external ID" icon="arrows-turn-right" href="/api-reference/redirect">
    `GET /redirect` — already have an IMDB / TMDB / TVDB / MAL / AniDB / etc. ID? Resolve it to a Simkl ID, then fetch from the cached detail endpoint. Faster and cheaper than text search.
  </Card>

  <Card title="By text" icon="magnifying-glass" href="/api-reference/simkl/search-by-text">
    `GET /search/{type}` — full-text search over titles. `type` is `movie`, `tv`, or `anime`.
  </Card>

  <Card title="By file name" icon="file" href="/api-reference/simkl/search-by-file">
    `POST /search/file` — pass a video file name and Simkl matches it to a title and episode.
  </Card>

  <Card title="Random" icon="dice" href="/api-reference/simkl/search-random">
    `POST /search/random` — surprise me. Useful for "What should I watch?" features.
  </Card>
</CardGroup>

<Note>
  **Writes don't need a Simkl ID at all.** [`/scrobble/*`](/guides/scrobble), [`/sync/history`](/api-reference/simkl/add-to-history), [`/sync/add-to-list`](/api-reference/simkl/add-to-list), and [`/sync/ratings`](/api-reference/simkl/add-ratings) accept any supported ID (IMDB, TMDB, TVDB, MAL, AniDB, …) directly and resolve server-side. The resolve-then-fetch pattern above is only needed when you want to **read** the Simkl record for a known external ID.
</Note>

## When to use each

<AccordionGroup>
  <Accordion title="By external ID — fastest path when you already know what you want">
    You have an IMDB / TMDB / TVDB / MAL / AniDB / AniList / Kitsu / etc. ID and want the matching Simkl record. Call [`GET /redirect`](/api-reference/simkl/redirect), read the `Location` header, parse the Simkl ID, then hit the cached detail endpoint:

    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    curl -sI "https://api.simkl.com/redirect?to=simkl&imdb=tt0944947&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
      -H "User-Agent: my-app-name/1.0" | grep -i ^location:
    # → location: https://simkl.com/tv/17465/game-of-thrones

    curl "https://api.simkl.com/tv/17465?extended=full&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
      -H "User-Agent: my-app-name/1.0"
    ```

    Both calls are cheap: `/redirect` is just an HTTP redirect (no JSON body); the detail endpoint is Cloudflare-cached by Simkl ID with automatic server-side cache invalidation. See the [Redirect](/api-reference/redirect) guide for the full stop-at-301 recipe.
  </Accordion>

  <Accordion title="By text — fuzzy match by title">
    Best for user-typed search bars. Pass `q` (the query) and pick the type:

    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    curl "https://api.simkl.com/search/tv?q=stranger+things&extended=full&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
      -H "User-Agent: my-app-name/1.0"
    ```
  </Accordion>

  <Accordion title="By file name — for media servers and scrapers">
    Pass a file name like `Stranger.Things.S01E03.1080p.WEB.x264-GROUP.mkv` and Simkl will identify the show and episode. Ideal for indexing a local library.
  </Accordion>

  <Accordion title="Random — for discovery features">
    Returns a random title, optionally filtered by genre, year, or watchlist status. Great for "next pick" buttons.
  </Accordion>
</AccordionGroup>

## Browse & discover

For browsing the catalog rather than running a query — top-rated lists, premieres, what's airing, or filtering by genre — use the dedicated browse endpoints:

| Surface                  | Endpoints                                                                                                                                                                            |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Top-rated / most-watched | [`/tv/best/{filter}`](/api-reference/simkl/get-best-tv), [`/anime/best/{filter}`](/api-reference/simkl/get-best-anime)                                                               |
| Premieres                | [`/tv/premieres/{param}`](/api-reference/simkl/get-tv-premieres), [`/anime/premieres/{param}`](/api-reference/simkl/get-anime-premieres)                                             |
| Airing now               | [`/tv/airing`](/api-reference/simkl/get-tv-airing), [`/anime/airing`](/api-reference/simkl/get-anime-airing)                                                                         |
| Filter by genre          | [`/movies/genres/...`](/api-reference/simkl/get-movies-genres), [`/tv/genres/...`](/api-reference/simkl/get-tv-genres), [`/anime/genres/...`](/api-reference/simkl/get-anime-genres) |

For trending and calendar surfaces, prefer the [CDN-cached data files](/api-reference/trending) on `data.simkl.in` — no per-user cost.