Quickstart

You need a workspace API key. See Authentication for setup.

Look up an item

curl -G https://api.refmatter.com/v1/items/lookup \
  -H "Authorization: Bearer $REFMATTER_API_KEY" \
  --data-urlencode "url=https://www.youtube.com/watch?v=jNQXAC9IVRw"

import { Refmatter } from '@refmatter/sdk';

const refmatter = new Refmatter({ apiKey: process.env.REFMATTER_API_KEY! });
const item = await refmatter.items.lookup(
  'https://www.youtube.com/watch?v=jNQXAC9IVRw',
);
console.log(item.platform, item.kind, item.usage.creditsCharged);

The response is the item itself. A trimmed response looks like this:

{
  "object": "item",
  "platform": "youtube",
  "kind": "video",
  "stats": { "views": 120000, "likes": 5300, "comments": 210 },
  "cached": false,
  "usage": {
    "creditsCharged": 1,
    "lines": [{ "part": "fetch", "credits": 1 }]
  }
}

The Refmatter-Credits-Charged response header reports the integer charge. Errors return 0.

Check the link for free (optional)

GET /v1/resolve checks the URL locally. It does not contact a platform and does not charge a credit.

curl -G https://api.refmatter.com/v1/resolve \
  -H "Authorization: Bearer $REFMATTER_API_KEY" \
  --data-urlencode "url=https://www.youtube.com/watch?v=jNQXAC9IVRw"

Keep the media

Create an import, wait for the reference, and read it. The reference includes verified media, a poster frame, a transcript when captions are available, and provenance.

curl -X POST https://api.refmatter.com/v1/imports \
  -H "Authorization: Bearer $REFMATTER_API_KEY" \
  -H "Idempotency-Key: quickstart-0001" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=jNQXAC9IVRw","mediaProfile":"analysis"}'

const importJob = await refmatter.imports.create({
  url: 'https://www.youtube.com/watch?v=jNQXAC9IVRw',
  mediaProfile: 'analysis',
});
const readable = await refmatter.imports.waitUntilReference(importJob.id);
const reference = await refmatter.references.get(readable.referenceId!);
console.log(reference.id, reference.mediaAvailability);

Choosing a media profile

`mediaProfile`	Video height cap	Use it for
`none`	no media	Metadata, provenance, and transcript only. Fastest and cheapest.
`analysis` (default)	480p	Transcripts, keyframes, structure analysis.
`full`	1080p	When the bytes themselves are the deliverable.

The profile is part of the idempotency hash: the same URL with a different profile is a different import.

Get started

Item data

Lists, search and comments

Reference library

SDK and agents

Policies

Choosing a media profile

​Choosing a media profile

Choosing a media profile