Skip to navigation
Get started

Making requests

Dialects, envelopes, pagination and the typed client
View as Markdown

Every procedure is a typed function grouped under a router, namespaced as router.procedure, for example release.byId or search.releases. Reads are queries (GET); writes are mutations (POST).

The response envelope

Every successful response wraps the procedure’s return value in result.data:

{
  "result": {
    "data": { "id": 895, "name": "300" }
  }
}

Errors use a different envelope; see Errors.

Two dialects over one API

You can speak to the API two ways over HTTPS. Both hit the same engine and return the same envelope.

The friendly dialect for humans and curl. Replace the dot in a procedure name with a slash, and pass input as ordinary query parameters (GET) or a JSON body (POST):

Read: query parameters
curl "https://api.homemediadb.com/v0/release/byId?id=895" \
  -H "Authorization: Bearer $HMDB_API_KEY"
Write: JSON body
curl -X POST https://api.homemediadb.com/v0/release/trivia/add \
  -H "Authorization: Bearer $HMDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"release_id": 895, "content": "First film released on HD-DVD in the UK."}'

Numeric inputs are coerced from strings, so ?id=895 validates against a number schema.

The split is unambiguous: a single dotted path segment (release.byId) is native tRPC; two or more slash segments (release/byId) is the REST facade. Every procedure is namespaced, so a real REST path is always at least two segments.

Pagination

List, search and discover procedures return a paged envelope. The page size is fixed at 20. Pass page (1-based, default 1) to walk the results:

{
  "result": {
    "data": {
      "page": 1,
      "total_pages": 3,
      "total_results": 42,
      "results": [ /* up to 20 items */ ]
    }
  }
}
Second page of results
curl "https://api.homemediadb.com/v0/search/releases?query=300&page=2" \
  -H "Authorization: Bearer $HMDB_API_KEY"

Caching

Static reference data, configuration.details and the enum fields it describes (mediums, region codes, video standards, packaging styles), rarely changes. Cache it on your side rather than fetching it on every request.

TypeScript SDK

For end-to-end type safety in TypeScript, install the SDK. Every procedure is typed in and out, and calls made in the same tick are batched into one request.

npm i @homemediadb/sdk
import { createClient } from '@homemediadb/sdk';
const hmdb = createClient({ apiKey: process.env.HMDB_API_KEY! });
const release = await hmdb.release.byId.query({ id: 895 });   // fully typed in + out
const hits = await hmdb.search.releases.query({ query: 'matrix' });
await hmdb.release.trivia.add.mutate({ release_id: 895, content: 'First film released on HD-DVD in the UK.' });

The client is a standard tRPC client. If you’d rather build your own (e.g. with @trpc/tanstack-react-query), the SDK also exports the AppRouter type.