Skip to navigation
Get started

Getting started

From zero to your first response in a couple of minutes
View as Markdown

The API is currently in Beta. Changes could happen at any point without notice, and uptime and general availability may be sparse.

This is the definitive list of currently available methods for querying the Home Media Database: releases, discs, tapes, titles, franchises, distributors and sets.

HMDb is built with tRPC rather than as a typical REST API. Each method is a typed procedure grouped under a router (release, disc, search, …). You can call a procedure two ways:

  • Over plain HTTPS: a REST-style facade or the native tRPC wire format. No client library needed.
  • With the TypeScript SDK: install @homemediadb/sdk for full end-to-end typings.

The base URL for every request is https://api.homemediadb.com/v0.

Quickstart

1

Create an API key

Every request, reads included, needs a user API key. Create a free one from your HMDb account, then set it in your shell:

export HMDB_API_KEY="ak_..."

See Authentication for the full walkthrough.

2

Make your first request

Fetch the static configuration: the mediums, region codes, video standards and packaging styles the client needs to read enum fields:

REST facade
curl https://api.homemediadb.com/v0/configuration/details \
  -H "Authorization: Bearer $HMDB_API_KEY"

Every successful response is wrapped in a result.data envelope:

{
  "result": {
    "data": {
      "images": { "base_url": "https://img.homemediadb.com/" },
      "mediums": [
        { "code": "UBD", "name": "Ultra-HD Blu-ray Disc", "type": "disc" },
        { "code": "VHS", "name": "Video Home System", "type": "tape" }
      ],
      "video_standards": ["NTSC", "PAL", "SECAM"],
      "region_codes": ["A", "B", "C", "1", "2", "3", "FREE", "NONE"],
      "packaging_styles": ["Keep Case", "Digipak", "Steelbook"]
    }
  }
}

Cache this response; it rarely changes.

3

Look something up

Search releases by name, then fetch one by its id:

Search, then fetch
curl "https://api.homemediadb.com/v0/search/releases?query=300" \
  -H "Authorization: Bearer $HMDB_API_KEY"
curl "https://api.homemediadb.com/v0/release/byId?id=895" \
  -H "Authorization: Bearer $HMDB_API_KEY"