canonical: https://jentic.com/apis/omdbapi.com/omdbapi

# Omdbapi OMDb

The Open Movie Database (OMDb) API is a free web service for fetching information about movies, TV shows, and episodes by title, IMDb ID, or search query. The full API is exposed through a single GET endpoint that accepts a handful of query parameters (title, IMDb ID, type, year, plot length, format) and returns canonical metadata such as plot, cast, ratings, runtime, and poster URL. Authentication uses a single apikey query parameter issued for free with a daily request quota.

## For AI agents

Look up movie, TV show, and episode metadata by title or IMDb ID. Returns plot, cast, ratings, runtime, and poster URL through a single GET endpoint.

## Scope

Does not provide streaming availability, trailer URLs, or box-office data - use for movie and TV metadata lookup only.

## Capabilities

- Look up a movie by exact title and optional release year
- Resolve a film or TV show from an IMDb ID such as tt1285016
- Search for titles matching a partial keyword and paginate through results
- Filter results to only movies, only series, or only episodes via the type parameter
- Retrieve short or full plot text on demand using the plot parameter
- Get poster image URLs for use in catalogues and recommendation lists

## Use cases

### Movie Catalogue Enrichment

When importing a watchlist or recommendation list with only titles, call GET / with t={title} to enrich each entry with plot, cast, ratings, and poster URL. The single-endpoint design means catalogue enrichment is one HTTP call per title with no schema setup required.

Example prompt: For each title in a watchlist of 50 movies, call GET /?t={title}&plot=full and store the returned plot, ratings array, and poster URL.

### IMDb ID Resolution

When a downstream system has IMDb IDs but needs human-readable metadata, call GET /?i={imdb_id} to resolve each ID to its full record. Useful for film sites that store IMDb IDs as foreign keys but render localised titles, ratings, and posters at runtime.

Example prompt: Call GET /?i=tt1285016&plot=short and extract Title, Year, Genre, and Director for display.

### Title Search and Discovery

For a 'find a film' agent, use GET /?s={keyword}&type=movie&page=1 to return up to 10 matching titles per page, paginate through results, and let the user pick one. Combine with the type filter to limit results to movies, series, or episodes.

Example prompt: Search for 'matrix' with type=movie, page=1 to return all matching titles with their IMDb IDs and posters.

### AI Agent Movie Research Assistant

An AI agent integrated through Jentic can answer 'what's the rotten tomatoes score of Inception' or 'list every Christopher Nolan film' by calling OMDb behind the scenes. Jentic stores the OMDb API key encrypted and injects it on each call, so the agent only references a credential handle.

Example prompt: Search Jentic for 'look up a movie', load the OMDb operation, and execute it with title='Inception' to return plot, ratings, and director.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/` | OMDb search and title lookup (accepts t, i, s, type, y, plot, r parameters) |

## Key resources

- **Title Lookup** — Single GET endpoint that accepts title, IMDb ID, or search query and returns movie or TV metadata.

## Why Jentic

- **Setup:** Wiring OMDb by hand means appending its apikey query parameter and getting the t, i, s, and type parameters right on the single root endpoint yourself. Through Jentic you install once, import OMDb from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** OMDb exposes a single read operation with no resource id in the URL path, so scoping is by operation: you limit the agent to the one operation it needs, looking up movie and TV metadata, and it can call nothing else.
- **Credential handling:** Your OMDb API key is stored once, encrypted, by your own Jentic One instance and appended to the apikey query parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'look up a movie' or 'find TV show metadata', and Jentic returns the OMDb operation with the t, i, s, and type parameters typed in its input schema so the agent calls it without browsing the reference docs.

## Related APIs

- **TMDB API** — Community-edited movie and TV database with richer image and trailer data.
- **TVmaze API** — TV-show-focused database with episode schedules and air dates.
- **Watchmode API** — Streaming-service availability lookup for any title.

## FAQ

### What authentication does the OMDb API use?

OMDb uses an API key passed as the apikey query parameter on every request. Jentic stores this key in the encrypted vault and appends it at execution time, so agents never embed it in code or logs.

### Can I look up a movie by IMDb ID with the OMDb API?

Yes. Pass the IMDb ID in the i query parameter (e.g. GET /?i=tt0816692) to fetch the canonical record. Pair with plot=full when you need the long plot summary instead of the short one.

### What are the rate limits for the OMDb API?

Free OMDb API keys are limited to 1,000 requests per day. Higher quotas require a paid Patreon supporter key. Cache results aggressively by IMDb ID - movie metadata changes rarely so cached records remain valid for weeks.

### How do I search for a movie by partial title through Jentic?

Search Jentic for 'search movies on omdb', load the GET / operation, and pass s={keyword}&type=movie. The endpoint returns up to 10 results per page; loop with page=2, page=3 to paginate.

### Is the OMDb API free?

OMDb offers a free tier with 1,000 requests per day. A Patreon-supporter key removes the throttle and unlocks the poster image API. Both tiers use the same single endpoint and parameter set.

### Does the OMDb API include streaming availability or trailers?

No. OMDb returns descriptive metadata (plot, cast, ratings, poster URL) but does not include streaming-service availability, trailer URLs, or box-office charts. Pair with a streaming-availability API if those are needed.

### Can I limit what my agent is allowed to do with the OMDb API?

Yes. OMDb exposes a single read-only operation for looking up movie and TV metadata by title, IMDb ID, or search keyword, with no resource id in the URL path, so scoping is done per operation. Because Jentic One is self-hosted, you set the rules on your own instance and grant your agent only that one lookup operation, meaning it can read movie and TV data and call nothing else. You also decide which stored credential the agent may use, so your OMDb API key is only ever attached to the calls you have explicitly permitted.