API overview

Authentication

Viewers sign in through the widget's built-in OAuth flow — there are no tokens for you to manage. If your host application already manages member sessions (SSO), pass a pre-issued member access token via the token attribute (or the client constructor) and the widget skips its in-widget sign-in. All authenticated requests send the token as a Bearer token in the Authorization header.

Organization scoping

Hedgehog is multi-tenant: every request is scoped to your organization, and every organization's data is fully isolated. IDs are typed UUIDs — an organization ID looks like Organization:550e8400-e29b-41d4-a716-446655440000, a comment ID like Comment:<uuid>.

Content resolution

Widgets take any stable external identifier — a slug or URL — as their id attribute and deterministically resolve it to a Content:<uuid> via UUID v5, namespaced to your organization. When calling the API directly, do the same resolution with the exported helper:

import { generateUuidV5, stripTypePrefix } from '@hedgehog/sdk-web'

const organizationUuid = stripTypePrefix(client.organizationId)
const contentId = `Content:${await generateUuidV5(organizationUuid, 'my-article-slug')}`

SDKs can also register the page URL hosting a content id (PUT /api/comments/:id/link, driven by the comments widget's page-url attribute). The URL must be on your registered site origin; the first registration wins and repeats are no-ops. Registered pages power the article context shown on notifications and profile comment feeds, with deep links back to the comment.

Pagination

List endpoints use key-based pagination: each page's paging.next is an opaque key you pass back to fetch the next page. No page numbers, no offsets.

const page = await client.comments.list(contentId)

const nextPage = page.paging.next
   ? await client.comments.list(contentId, { next: page.paging.next })
   : null

Client API surface