Tổng quanBắt đầu nhanhTài liệu tham khảo APIGiáNhật ký thay đổiTrạng tháiNhận khóa API
Nhà phát triểnBắt đầu nhanhTài liệu tham khảo APIBảng điều khiểnBảng giáNhật ký thay đổi APITrạng thái dịch vụ
Khám pháPhimPhim bộTrợ giúpĐiều Khoản Dịch VụChính Sách Bảo MậtTải ứng dụngChính Sách CookieBảng giáHoàn tiền và HủyChính sách Sử dụng Được chấp nhậnChủ sở hữu quyềnTrạng thái dịch vụKiểm tra thông báo gỡ bỏCó gì mới
·

© 2026 Wambesha

v0.110.0
Tổng quan

Discovery

  • SearchGET
  • DiscoverGET
  • LookupGET
  • GenresGET
  • Similar titlesGET

Titles

  • Batch titlesGET
  • Title recordGET
  • SeasonsGET
  • EpisodesGET
  • CreditsGET
  • ImagesGET
  • Where a title is heldGET

People

  • PersonGET
  • FilmographyGET

Changes

  • Change feedGET
  • ChangelogGET

Account

  • Plan and usageGET
  • Usage historyGET
  • Recent requestsGET
  • KeysGET
  • Rotate keyPOST

21 trên 21 điểm cuối

Tài liệu tham khảo API chỉ có bằng tiếng Anh.

Tài liệu tham khảo API — v1

https://api.wambesha.com · Xác thực Bearer · JSON

Mọi điểm cuối của v1, kèm theo tham số, ví dụ yêu cầu và phản hồi, cùng các lỗi có thể trả về. Phần mô tả điểm cuối được viết bằng tiếng Anh.

Nhật ký thay đổi

Xác thực

Your API key, presented as a Bearer token. Keys are per-account and carry a plan; the plan decides which endpoints answer and what your quota is. Never embed a key in a browser client — it is a credential, and a browser cannot keep one.

HTTP
Authorization: Bearer $WAMBESHA_API_KEY

Với những điểm cuối chấp nhận khóa demo công khai, đoạn mã “Dùng thử” của điểm cuối đó đã chứa sẵn khóa này nên có thể chạy ngay như vậy; mọi đoạn mã khác đều cần khóa của riêng bạn. Khóa demo chỉ dùng để dùng thử API: khóa được thay đổi hằng ngày, có thể bị tắt bất cứ lúc nào và tuyệt đối không được dùng trong môi trường vận hành thực tế. Hãy dùng khóa của riêng bạn cho mọi thứ bạn xây dựng.

Tiêu đề phản hồi

  • X-Request-IDMọi phản hồi đã xác thực

    The id of this request, on every response - success or error. Quote it to support: it is how we find your request in our logs. An X-Request-ID you send is honoured and echoed back, so you can use your own; otherwise we generate one. /v1 error bodies carry no trace id of their own.

  • X-Quota-ResetMọi phản hồi đã xác thực

    RFC 3339 instant at which the billing period rolls. Present on every response to a request whose key was metered - every 2xx, every error a handler returned, and the quota 429. Absent on a refusal that happens before metering: a missing or unknown key (401), a restricted key or a plan that does not carry the endpoint (403), a public demo-key gate refusal, and the pre-authentication flood throttle.

  • X-Calls-RemainingMọi phản hồi đã xác thực

    Requests left in the period after this one, never below 0. Present whenever X-Quota-Reset is (see there for when a response carries no quota headers).

  • X-Verifications-RemainingMọi phản hồi đã xác thực

    How many verifications you can still make before a limit stops you. The daily limit and the monthly allowance are counted separately; this is whichever of the two runs out first. Sent whenever X-Quota-Reset is.

  • X-Quota-GraceMọi phản hồi đã xác thực

    true when THIS request fell inside the 10% grace band above a monthly ceiling. A grace request is served and is not billed; treat true as "back off now", not as headroom. Always true or false, never absent when the other quota headers are present.

  • Retry-AfterChỉ khi phản hồi 429

    Seconds to wait before retrying. On every 429 - the quota hard stop, the public demo key's limits, and the pre-authentication flood throttle (which carries this header alone, because no key has been read yet).

  • X-Demo-Challenge-ModeChỉ với khóa demo

    Sent only on responses to the public demo key. The value interactive asks the documentation page to show the visible verification widget - it is sent once a browser has made more than five runs in ten minutes or has received a 429. The page then repeats the header, X-Demo-Challenge-Mode: interactive, on its next request, with the widget's token in X-Demo-Challenge. Requests made with your own key never receive it.

Lỗi

Mọi lỗi đều có cùng một phần thân: trạng thái HTTP, một mã ổn định để bạn rẽ nhánh xử lý, một thông báo dành cho người đọc và các lỗi trường khi có giá trị sai. Để chỉ rõ một yêu cầu khi liên hệ với chúng tôi, hãy dùng tiêu đề phản hồi X-Request-ID của yêu cầu đó.

Phản hồi đã ghi lại

Content-Type
application/json
X-Request-ID
5f3c9a1e7b2d4c60

GET/v1/search

{
  "timestamp": "2026-09-27T12:00:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Enter at least 2 characters to search.",
  "path": "/v1/search",
  "errors": [
    {
      "field": "q",
      "rejectedValue": "a",
      "message": "Enter at least 2 characters to search."
    }
  ],
  "metadata": {
    "errorCode": "CATALOG_SEARCH_QUERY_TOO_SHORT"
  },
  "code": "validation-failed"
}

400

  • validation-failed400405

    The request is not one this operation accepts - a parameter outside its rule, a missing required parameter, an unsupported language, or a method the route does not take.

    Cách xử lýFix the request; errors names the parameter. Retrying it unchanged fails the same way.

  • cursor-invalid400

    The cursor is malformed, stale, from a different filter set or sort, or past what your key may page.

    Cách xử lýDrop the cursor and request the first page again.

  • unauthenticated401

    No key, or a key that is unknown, malformed, expired or revoked - one answer for all of them. Also what a switched-off public demo key answers.

    Cách xử lýSend a valid key as Authorization: Bearer <key>; if it was rotated, use its replacement.

  • forbidden403

    The key is valid but a restriction its owner set - a scope, an IP allowlist, a referrer allowlist - excludes this request. Also a key rotating a key other than itself.

    Cách xử lýCall from an allowed place or change the key's restrictions in the console.

  • plan-required403

    Your plan does not include this operation or this freshness, or the public demo key was used for something it cannot reach.

    Cách xử lýUpgrade the plan, or use your own key rather than the demo key.

  • challenge-required403

    A browser call with the public demo key carried no valid bot-check token.

    Cách xử lýComplete the check on the page and run the request again. Not sent to paying keys.

  • not-found404

    Nothing matches the reference, or the reference is not a valid id.

    Cách xử lýCheck the id; a merged record answers 200 with its survivor, so 404 means it never existed here.

  • conflict409

    The request contradicts current state - a key already rotated, revoked or expired, or an identifier that matches several records.

    Cách xử lýRead metadata.errorCode; rotate the replacement key, or disambiguate the identifier.

  • gone410

    The record existed and has been removed. No reason is given, by design.

    Cách xử lýDrop it from your mirror; /v1/changes reports it as removed.

  • quota-exhausted429

    A plan ceiling is reached - requests (daily or monthly) or verifications. The message names which.

    Cách xử lýWait for Retry-After (the daily window resets at midnight UTC, the monthly one at X-Quota-Reset), or upgrade. The refused call is not charged.

  • rate-limited429

    Too many requests too fast - the per-address flood throttle, or the public demo key's own limits, temporary blocks and in-flight cap.

    Cách xử lýWait Retry-After seconds, then slow down.

  • upstream-unavailable503

    We could not meter or serve the request right now. Never served unmetered, never charged.

    Cách xử lýRetry with exponential backoff.

Quản lý phiên bản

v1 không bao giờ phá vỡ tương thích: đường dẫn, tham số bắt buộc và các trường phản hồi không thay đổi trong v1. Có thể bổ sung trường và điểm cuối mới, và chúng sẽ được thông báo trước trong nhật ký thay đổi. Cách hoạt động của việc lập phiên bản

Điểm cuối

Discovery

  • GET/v1/searchRelevance search across titles and people. Every response carries a titles list and a people list, and the two page separately. Spends no verification.
  • GET/v1/discoverBrowse the catalogue by genre, year range, country, type and minimum rating, in one of four fixed sort orders. Returns title ids. Spends no verification.
  • GET/v1/lookupTurn one external identifier - IMDb, TMDB, TVDB - or a catalog UUID into our title id, with every identifier we hold for it. Spends no verification.
  • GET/v1/genresThe fixed genre list, with the slugs /v1/discover filters on. Spends no verification.
  • GET/v1/recommendationsTitles similar to one or more seed titles, scored 0-1 and above a fixed threshold. Spends no verification.

Titles

  • GET/v1/titlesUp to 100 title records in one call, in the order asked; unknown or withdrawn ids come back in missing rather than failing the call. Spends no verification.
  • GET/v1/titles/{titleRef}One title record - film, series, season or episode - by public id or UUID, optionally with credits, images and similar titles inlined. Spends no verification.
  • GET/v1/titles/{titleRef}/seasonsThe season guide of a series - numbers, names and episode counts. A film answers an empty list. Spends no verification.
  • GET/v1/titles/{titleRef}/episodesThe episodes of a series, or of one season, in season and episode order. Spends no verification.
  • GET/v1/titles/{titleRef}/creditsCast in billing order and crew grouped by department, paged. Spends no verification.
  • GET/v1/titles/{titleRef}/imagesEvery stored rendition of a title's posters, backdrops, logos and stills, with pixel sizes. Spends no verification.
  • GET/v1/titles/{titleRef}/sourcesWhere a title is held, confirmed now: the institution, the page address and the formats it lists. The one endpoint that spends a verification.

People

  • GET/v1/people/{personRef}One person record - biography, photo and best-known titles - by public id or UUID. Spends no verification.
  • GET/v1/people/{personRef}/filmographyEverything a person is credited on, with the character or job, paged and sortable by year or title. Spends no verification.

Changes

  • GET/v1/changesWhat changed in the catalogue since a moment you name - records added, updated, merged or removed - for keeping a mirror in step. Spends no verification.
  • GET/v1/changelogRelease notes for this API, newest first - what changed, when, and whether it can break an integration. Spends no verification.

Account

  • GET/v1/accountYour plan, this period's usage against its allowances, a period-end projection and your spend controls. Never charged, even past your ceiling.
  • GET/v1/account/usageRequests, verifications, errors and latency over the last day, week or month, broken down by endpoint and key. Never charged.
  • GET/v1/account/requestsThe last requests made with your keys - method, endpoint, status, latency - kept for 7 days. Never charged.
  • GET/v1/account/keysEvery API key on your account - name, prefix, last four, environment, restrictions and last use. Never the secret. Never charged.
  • POST/v1/account/keys/{keyId}/rotateIssue a new secret for the key you are calling with; the old one keeps working for 24 hours. The new secret is shown exactly once.