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

# Browse and annotate

> List the catalog, page with cursors, and add human notes without fighting refreshes.

## List

```bash theme={null}
curl "https://api.refmatter.com/v1/references?state=ready&platform=youtube&limit=20" \
  -H "Authorization: Bearer $REFMATTER_API_KEY"
```

Pass `nextCursor` back as `cursor` for the next page. Cursors are signed and expire; never build them yourself.

## Annotate

Updates are optimistic: send the `revision` you last read. A stale revision is `409 revision_conflict`; read again and retry.

<CodeGroup>
  ```bash curl theme={null}
  curl -X PATCH https://api.refmatter.com/v1/references/$REFERENCE_ID \
    -H "Authorization: Bearer $REFMATTER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"revision":3,"customTitle":"Hook study: cold open","tags":["hook","talking-head"],"notes":"Cut at 0:07 works because…"}'
  ```

  ```ts TypeScript theme={null}
  const reference = await refmatter.references.get(referenceId);
  await refmatter.references.update(referenceId, {
    revision: reference.revision,
    customTitle: 'Hook study: cold open',
    tags: ['hook', 'talking-head'],
  });
  ```
</CodeGroup>

Human-authored fields are never touched by a refresh of the source observation.

## Delete

`DELETE /v1/references/{id}` soft-deletes the reference and releases its media hold. Other workspaces' references to the same content are unaffected.