> ## 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.

# Quickstart

> Create your first reference from a YouTube URL.

You need a workspace API key. Keys are issued per workspace by the workspace owner (see [Authentication](/guides/authentication)); during early access we issue the first one for you.

<Steps>
  <Step title="Submit the URL">
    <CodeGroup>
      ```bash curl theme={null}
      curl -X POST https://api.refmatter.com/v1/ingestions \
        -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"}'
      ```

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

      const refmatter = new Refmatter({ apiKey: process.env.REFMATTER_API_KEY! });
      const ingestion = await refmatter.ingestions.create({
        url: 'https://www.youtube.com/watch?v=jNQXAC9IVRw',
        mediaProfile: 'analysis',
      });
      console.log(ingestion.id, ingestion.state); // "accepted"
      ```
    </CodeGroup>

    The response is `202 Accepted` with the ingestion projection and a `Location` header. Replaying the same idempotency key and body returns the original ingestion with `X-Idempotent-Replay: true`.
  </Step>

  <Step title="Wait for the reference">
    Poll the ingestion until `referenceId` is set: that happens within seconds, once metadata, provenance, and the transcript are durable. Media bytes keep transferring in the background (`state` stays `running` until they are verified); wait for `succeeded` only if you need the bytes right away.

    <CodeGroup>
      ```bash curl theme={null}
      curl https://api.refmatter.com/v1/ingestions/$INGESTION_ID \
        -H "Authorization: Bearer $REFMATTER_API_KEY"
      ```

      ```ts TypeScript theme={null}
      const readable = await refmatter.ingestions.waitUntilReference(ingestion.id, {
        onUpdate: (update) => console.log(update.state, update.progress?.stage),
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Read the reference">
    A succeeded ingestion carries `referenceId`.

    <CodeGroup>
      ```bash curl theme={null}
      curl https://api.refmatter.com/v1/references/$REFERENCE_ID \
        -H "Authorization: Bearer $REFMATTER_API_KEY"
      ```

      ```ts TypeScript theme={null}
      const reference = await refmatter.references.get(readable.referenceId!);
      console.log(reference.sourceObserved.title, reference.mediaAvailability);
      ```
    </CodeGroup>
  </Step>
</Steps>

<Tip>
  `refmatter.resolve(url)` in the SDK does all three steps and returns `{ ingestion, reference }` as soon as the reference is readable; pass `{ waitFor: 'media' }` to wait for the bytes too.
</Tip>

## 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 ingestion.