Edge API (OpenAPI)

This page is generated from openapi.yaml at build time. The machine-readable spec is a deliverable of this package.

API version: 0.1

Auth

Key	Pattern	Used for
Publishable (uv_pk_...)	Body/query key	POST /v1/sdk/bootstrap, POST /v1/sdk/responses, POST /v1/dismissals
Secret (uv_sk_...)	Authorization: Bearer or X-UserVane-Key	POST /v1/sdk/tokens, GET /v1/sdk/pending-scores, POST /v1/sdk/pending-scores/ack, privacy

The secret key is server-only. Never ship it to the browser.

Endpoints

POST /v1/sdk/bootstrap

Bootstrap surveys, suppression, and unbound show-tokens

Returns active survey definitions, the server-authoritative suppression set for the respondent, and per-survey single-use show-tokens (when the respondent is eligible). Caps and quiet period are decided here only (issue-time). Public (publishable) key.

Auth: publishable key

Parameters

Name	In	Description
key	query	Publishable key (also accepted in body)
userId	query	Respondent id (also accepted in body)

Request body

Field	Type	Required	Description
key	string		Publishable key
userId	string
traits	object

Success response

Field	Type	Required	Description
surveys	array	yes
suppression	array	yes	Survey ids this respondent has answered or dismissed
showTokens	object		surveyId -> single-use show-token; missing means gated

Status codes: 200, 400, 401, 403, 429

POST /v1/sdk/responses

Submit a survey response (token-verified)

Ingests a rating after verifying the single-use show-token. Caps are never enforced at submit; a valid unused token is always accepted. Publishable key in body or query. Optional correlation fields (sessionId, observationId) must match token-attested values when the token was session-bound.

Auth: publishable key

Parameters

Name	In	Description
key	query	Publishable key (also accepted in body)

Request body

Field	Type	Required	Description
showToken	string	yes
surveyId	string	yes
rating	integer	yes	Outer bound; per-type range enforced after survey load
text	string
followUpRequested	boolean
userId	string
traits	object
key	string		Publishable key
sessionId	string		Must match token-attested session when bound
observationId	string
taskType	string		Untrusted display metadata for PM segmentation
identityKind	"identified" | "anon-device" | "anon-conversation"

Success response

Field	Type	Required	Description
ok	true	yes
id	string	yes
at	string	yes

Status codes: 201, 400, 401, 403, 404, 409, 429

POST /v1/dismissals

Record a dismissal (token-verified)

Records that the respondent dismissed the ask and adds the survey to suppression. Same token rules as response submit. Publishable key.

Auth: publishable key

Parameters

Name	In	Description
key	query

Request body

Field	Type	Required	Description
showToken	string	yes
surveyId	string	yes
userId	string	yes
key	string

Success response

Field	Type	Required	Description
ok	true	yes
id	string	yes
at	string	yes

Status codes: 201, 400, 401, 403, 404, 429

POST /v1/sdk/tokens

Mint session-bound show-tokens (server-only)

Mints v2 show-tokens bound to the provided sessionId (and optional observationId / taskType). Auth is secret key only; a publishable key Bearer fails. Same gating as bootstrap (suppression, quiet period, monthly cap, per-survey max). Empty tokens means gated, not an error. Never call from the browser.

Auth: secret key

Request body

Field	Type	Required	Description
respondentId	string	yes
sessionId	string	yes	Authoritative server session id (Langfuse / AI SDK)
observationId	string
taskType	string
surveyId	string		When set, only mint for this active survey

Success response

Field	Type	Required	Description
tokens	object	yes	surveyId -> v2 show-token bound to sessionId
suppression	array	yes
issuedAt	string	yes

Status codes: 200, 400, 401, 429

GET /v1/sdk/pending-scores

Poll linked scores awaiting Langfuse push

Tenant-scoped queue of linked responses with score_state=pending (and optionally failed). Serves verbatim PII for this project only. Secret key only. Used by @uservane/langfuse-push.

Auth: secret key

Parameters

Name	In	Description
limit	query	Page size (server-capped)
includeFailed	query	When true, also return previously failed rows
cursor	query	Opaque keyset cursor from a prior nextCursor

Success response

Field	Type	Required	Description
scores	array	yes
nextCursor	string

Status codes: 200, 400, 401, 429

POST /v1/sdk/pending-scores/ack

Ack delivered or failed pending scores

Adapter reports per-id delivered or failed. Updates only this project’s rows; foreign ids are a silent no-op. Secret key only.

Auth: secret key

Request body

Field	Type	Required	Description
results	array	yes

Success response

Field	Type	Required	Description
ok	true	yes
updated	integer	yes

Status codes: 200, 400, 401, 429

GET /v1/privacy/export

Export responses (DSAR / admin)

Secret-key export of response rows. Optional filters by respondentId, email (imported rows; hashed server-side to imp_), and surveySlug.

Auth: secret key

Parameters

Name	In	Description
respondentId	query	Live SDK userId or known imp_ hash
email	query	Natural identity for imported Delighted rows
surveySlug	query

Success response

Field	Type	Required	Description
projectId	string	yes
exportedAt	string	yes
count	integer	yes
responses	array	yes

Status codes: 200, 400, 401, 404

DELETE /v1/privacy/erase

Erase responses (DSAR / purge)

Secret-key erasure. Modes:

• respondent: respondentId and/or email (deletes responses and dismissals; retains hashed suppression so never-re-prompt survives)
• survey: surveySlug alone (per-survey purge)
• account: account=true (full project purge)

Auth: secret key

Parameters

Name	In	Description
respondentId	query
email	query
surveySlug	query
account	query	Full account purge when set

Success response

Field	Type	Required	Description
ok	true	yes
mode	"respondent" | "survey" | "account"	yes
respondentIds	array
responsesDeleted	integer
dismissalsDeleted	integer
suppressionRetained	integer
surveySlug	string
note	string

Status codes: 200, 400, 401, 404

Download

The OpenAPI 3 document lives at the package root as openapi.yaml and is copied into the static build under /openapi.yaml.