Browse and annotate - Refmatter

List

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.

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…"}'

const reference = await refmatter.references.get(referenceId);
await refmatter.references.update(referenceId, {
  revision: reference.revision,
  customTitle: 'Hook study: cold open',
  tags: ['hook', 'talking-head'],
});

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.