> ## Documentation Index
> Fetch the complete documentation index at: https://docs.refmatter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> @refmatter/sdk is generated from the API contract, so it cannot drift from the server.

```bash theme={null}
npm install @refmatter/sdk
```

```ts theme={null}
import { Refmatter } from '@refmatter/sdk';

const refmatter = new Refmatter({ apiKey: process.env.REFMATTER_API_KEY! });

// URL in, reference out, as soon as metadata and transcript are readable.
const { ingestion, reference } = await refmatter.resolve(
  'https://www.youtube.com/watch?v=jNQXAC9IVRw',
  { onUpdate: (update) => console.log(update.state) },
);
if (reference === null) {
  throw new Error(`${ingestion.outcomeCode}: ${ingestion.outcomeMessage}`);
}

// Browse, annotate, keep the bytes longer, download.
const page = await refmatter.references.list({ limit: 20, platform: 'youtube' });
await refmatter.references.update(reference.id, {
  revision: reference.revision,
  tags: ['hook'],
});
await refmatter.references.setMediaHold(reference.id, 90);
const access = await refmatter.media.access(reference.primaryMediaId!);
```

## Surface

| Group        | Methods                                                                             |
| ------------ | ----------------------------------------------------------------------------------- |
| `ingestions` | `create`, `get`, `cancel`, `waitUntilReference`, `waitUntilSettled`                 |
| `references` | `list`, `get`, `transcript`, `update`, `delete`, `setMediaHold`, `releaseMediaHold` |
| `media`      | `access`                                                                            |
| `sources`    | `routes`                                                                            |
| top level    | `resolve(url, { waitFor?: 'reference' \| 'media' })`                                |

Every method throws `RefmatterError` (`status`, `code`, `requestId`, `retryable`) on failure. `refmatter.raw` is the underlying [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) client typed with the full contract, and the `paths`, `operations`, and `components` types are exported for your own wrappers.

## Options

| Option      | Default                     | Notes                       |
| ----------- | --------------------------- | --------------------------- |
| `apiKey`    | required                    | Workspace API key           |
| `baseUrl`   | `https://api.refmatter.com` | Origin without `/v1`        |
| `fetch`     | global `fetch`              | Inject for tests or proxies |
| `timeoutMs` | 30000                       | Per request                 |

Node 18+ and any runtime with `fetch` and `crypto.randomUUID`.