Skip to main content
  • Base URL: https://api.refmatter.com
  • Versioning: all product endpoints live under /v1. Additive changes ship without a version bump; breaking changes get /v2.
  • Authentication: Authorization: Bearer <workspace API key>. See Authentication.
  • Content type: JSON in, JSON out. Timestamps are RFC 3339 UTC. Resource ids, such as import, reference, and media ids, are UUIDs; items and accounts are known by natural keys, <platform>:<native id> such as tiktok:7437269251355921707, and a resolution’s id is the natural key of what the URL points to.
  • Idempotency: POST /v1/imports requires an Idempotency-Key header.
  • Credits: GET /v1/items/lookup, GET /v1/accounts/lookup, GET /v1/items, GET /v1/comments, and GET /v1/search answer with Refmatter-Credits-Charged, an integer that is 0 on every error and access refusal, and with Refmatter-Credits-Remaining, the workspace balance after that response. A workspace has a balance of credits: credits are added to it, and charged work subtracts from it. When the balance reaches zero, anything that would charge answers 402 insufficient_credits without contacting the platform and without charging; free work keeps working, including a repeat within your maxAge, an empty page, GET /v1/resolve and imports. GET /v1/workspaces/{workspaceId}/usage reports credits with balance, granted and spent. See Look up an item, Look up an account, and List an account’s items.
  • Timing: a successful lookup carries Server-Timing with total and, when those phases ran, fetch and persist durations in milliseconds. Errors carry none.
  • Errors: one envelope with a stable code; see Errors. A 429 carries Retry-After in whole seconds.
  • Contract: the machine-readable source of truth is GET https://api.refmatter.com/openapi.json.