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

# EtMDB REST API v1

Jentic publishes the only available OpenAPI specification for EtMDB REST API v1, keeping it validated and agent-ready. EtMDB is the Ethiopian Movie Database, a directory of Ethiopian films, cast, crew, cinema schedules, and showtimes. The REST API exposes search-by-keyword endpoints across cinema, cinema schedule and showtime, company credits, filmography, genre, jobs, media, movie cast, movies, news, people, showtimes, and watchlists. Each resource has a search-by-id form and a searchall variant for broader matches.

## For AI agents

Search Ethiopian Movie Database records - movies, cast, crew, companies, cinema schedules, and showtimes - by title, name, or keyword to power Ethiopian film discovery.

## Scope

Does not handle ticket booking, streaming playback, or content uploads - use for searching Ethiopian movie, cast, cinema, schedule, and news records only.

## Capabilities

- Search Ethiopian movies by title and retrieve cast, crew, and metadata
- Look up cinema details, schedules, and showtimes for a given movie or location
- Find filmography and credits for an Ethiopian actor, director, or production company
- Search news and articles tagged with a movie title or keyword
- Build a watchlist or recommendations feed by querying the movie and genre endpoints
- Pair searchall endpoints with the matching search endpoints for broad-then-narrow lookups

## Use cases

### Movie discovery feed for an Ethiopian film app

A consumer app pulls movies, genre listings, and people from EtMDB to power its discovery and search screens. Title queries hit `/api/v1/movie/search/{movie_title}` for fast lookups, while category browsing uses `/api/v1/genre/searchall/{movie_genre_type}` to fetch full lists. Cast detail screens stitch `/api/v1/movie-cast/search` and `/api/v1/people/search` together for each title.

Example prompt: GET `/api/v1/movie/search/{movie_title}` for the user's query, then for each result GET `/api/v1/movie-cast/search/{movie_title}` and `/api/v1/genre/search/{movie_title}` to populate the detail screen.

### Cinema showtime lookup and ticketing assistant

A ticketing chat assistant resolves a user's 'what's playing tonight at Cinema X?' request by calling `/api/v1/cinema-shedule-showtime/searchall/{param}` or `/api/v1/cinema-detail/search/{cinema_name}.` The response lists movies, screens, and start times so the assistant can present the next few showings; the user is then handed off to the cinema's booking flow.

Example prompt: GET `/api/v1/cinema-detail/search/{cinema_name}` to resolve the cinema id, then GET `/api/v1/cinema-shedule-showtime/search/{movie_title}` for each requested movie.

### Editorial dashboard for Ethiopian film journalists

Editors at an Ethiopian entertainment publication pull `/api/v1/news/search/{title}` and `/api/v1/filmography/search/{movie_title}` to assemble a single dashboard view of recent coverage and historical filmography for whichever film they are profiling. `/api/v1/people/search/{user}` fills in the actor side, and `/api/v1/company/search/{company_name}` surfaces the production studio.

Example prompt: For the article subject, GET `/api/v1/news/search/{title}`, `/api/v1/filmography/search/{movie_title}`, and `/api/v1/company/search/{company_name}` and assemble the merged result for the editor.

### AI agent recommending Ethiopian films via Jentic

A recommendation agent answering 'suggest an Ethiopian drama from the last five years' uses Jentic to resolve the right EtMDB endpoints, queries genre and movie searches, and returns a ranked shortlist. Through Jentic, the OAuth2 credentials are held in the vault and the agent only sees a scoped execution token.

Example prompt: Search Jentic for 'find Ethiopian films by genre', execute GET `/api/v1/genre/searchall/{movie_genre_type}` with 'drama', then for each result fetch `/api/v1/movie/search/{movie_title}` to enrich and rank the response.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/movie/search/{movie_title}` | Search for a movie by title |
| GET | `/api/v1/movie-cast/search/{movie_title}` | Get cast for a movie |
| GET | `/api/v1/people/search/{user}` | Search for a person (actor/crew) |
| GET | `/api/v1/cinema-shedule-showtime/search/{movie_title}` | Get cinema showtimes for a movie |
| GET | `/api/v1/genre/search/{movie_title}` | Look up genre information for a movie |
| GET | `/api/v1/news/search/{title}` | Search news or articles by title |

## Key resources

- **Movies** — Search movies by title and pull associated metadata
- **Movie Cast** — Look up cast lists for a film
- **People** — Search actors, directors, and other film professionals
- **Filmography** — Retrieve filmography for a person or company
- **Cinemas** — Look up cinemas, schedules, and showtimes
- **Genre** — Browse movies by genre
- **Companies** — Search production companies and their credits
- **News** — Find news and articles linked to titles or people

## Why Jentic

- **Setup:** Wiring the EtMDB REST API by hand means running its OAuth2 flow, refreshing tokens, and picking the right movie, cast, cinema, schedule, or news search path yourself. Through Jentic you install once, import the EtMDB REST API from the API Directory, store the OAuth credentials once, and your agent calls it.
- **Permission scoping:** The EtMDB REST API is read-only search, with the search term travelling in the URL path (`/movie/search/{movie_title}`) rather than a resource you own, so scope the agent to the search operations it needs. You choose which operations are allowed, so nothing beyond the searches you pick runs unless you add it.
- **Credential handling:** Your EtMDB OAuth2 client secret and access token are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find an Ethiopian movie by title' or 'list showtimes for a movie', and Jentic returns the matching search operation with its input schema so the agent calls the right endpoint without enumerating the reference docs.

## Related APIs

- **TMDB API** — TMDB is the global counterpart with much broader title coverage but limited Ethiopian-specific data.
- **OMDb API** — OMDb returns IMDb-derived metadata for international films.
- **IMDb API (imdb-api.com)** — Third-party IMDb wrapper covering global film metadata.

## FAQ

### Why is there no official OpenAPI spec for EtMDB REST API v1?

EtMDB does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call EtMDB REST API v1 via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the EtMDB REST API use?

The EtMDB REST API uses OAuth 2.0 for access. Through Jentic, the OAuth credentials are stored encrypted in the vault and exchanged for a scoped execution token at call time, so the raw token never enters the agent's prompt context.

### What's the difference between /search/ and /searchall/ on EtMDB endpoints?

Most resources expose two variants: `/search/{key}` returns a narrower match scoped to the supplied key (movie title, cinema name, person name) and `/searchall/{param}` returns the broader list of matches. Use /searchall when the user gives a partial or category-style input and /search when they give an exact identifier.

### What are the rate limits for the EtMDB REST API?

EtMDB does not document an explicit rate-limit policy in this spec. Treat each search as a single request, cache popular results client-side, and back off on any 429 or 5xx response rather than retrying tight loops.

### How do I find showtimes for a movie through Jentic?

Search Jentic for 'Ethiopian movie showtimes'. Jentic returns GET `/api/v1/cinema-shedule-showtime/search/{movie_title}.` Execute it with the movie title and the response includes the cinemas, screens, and start times currently scheduled for that title.

### Can I add or update records via this API?

No. Every endpoint in this spec is a GET search; the EtMDB REST v1 surface is read-only. Submitting new movies, cast, or cinema entries is handled through EtMDB's editorial process, not through this API.

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

Yes. Because Jentic One is self-hosted, you set the rules for which operations your agent may call, and the EtMDB REST API is entirely read-only search, so you simply allow only the specific search operations it needs. For example, you can permit a movie lookup at `/api/v1/movie/search/{movie_title}` and cast lookups at `/api/v1/movie-cast/search/{movie_title}` while leaving people, cinema showtime, genre, or news searches disabled. Nothing beyond the search operations you pick will run unless you add it, and your OAuth2 credentials stay held by your own instance and are injected only at call time.