> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.homemediadb.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.homemediadb.com/_mcp/server.

# Making requests

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`:

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

Errors use a different envelope; see [Errors](/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.

#### REST facade

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`**

```bash title="Read: query parameters"
curl "https://api.homemediadb.com/v0/release/byId?id=895" \
  -H "Authorization: Bearer $HMDB_API_KEY"
```

**`Write: JSON body`**

```bash title="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.

#### Native tRPC

The wire format typed clients use. Keep the **dot** in the procedure name, and pass input as a single URL-encoded JSON `input` query parameter:

**`Read`**

```bash title="Read"
curl "https://api.homemediadb.com/v0/release.byId?input=%7B%22id%22%3A895%7D" \
  -H "Authorization: Bearer $HMDB_API_KEY"
```

`%7B%22id%22%3A895%7D` is `{"id":895}` URL-encoded. This dialect also supports tRPC request batching. The [API reference](/api-reference) documents each procedure in this form.

> **Info**
>
> 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:

```json
{
  "result": {
    "data": {
      "page": 1,
      "total_pages": 3,
      "total_results": 42,
      "results": [ /* up to 20 items */ ]
    }
  }
}
```

**`Second page of results`**

```bash title="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`](/api-reference) 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.

```bash
npm i @homemediadb/sdk
```

```ts
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](https://trpc.io) client. If you'd rather build your own (e.g. with `@trpc/tanstack-react-query`), the SDK also exports the `AppRouter` type.