> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userkit.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# This person's points, level and badges
> What the widget renders for the person holding the page: their balance, where it places them, and their shelf.
**Nothing here writes, and there is no endpoint that does.** A point is a fact landing — the same rule that gives an onboarding step no "mark as done". The moment a page can ask for points, the page's network tab is the game. Your own backend can grant one with `POST /v1/points`, which is a program you control.
An anonymous session is answered `200` with zeros rather than `401`: the widget runs on your landing page, and nothing pays a visitor. What somebody earns after they sign in follows them — the anonymous-to-identified merge moves the ledger, so points earned in the session that became an account are not lost.
`level` and `next_level` are `null` when no level is defined or when there is nothing above — draw the progress bar off `points_to_next`, which is `null` at the top.
A badge's CONDITION deliberately does not travel. Handing somebody "unlock at 40 invites" is handing them the rule to farm, and a hidden badge would stop being a surprise the moment anybody opened the network tab.
A LEVEL's conditions travel and a BADGE's do not, on the same response. It is the same principle twice: a badge is a surprise you are entitled to keep — handing somebody "unlock at 40 invites" hands them the rule to farm — while a rung is a goal your product is ASKING them to reach, and a progress bar that cannot say "2 courses to go" is a bar filling for reasons nobody can act on. The one thing withheld is the NAME of an audience.
## OpenAPI
````yaml /api-reference/openapi.json get /v1/contact/gamification
openapi: 3.1.0
info:
title: UserKit API
version: 1.0.0
description: >-
The HTTP surface of UserKit.
Two planes share one API. The **staff plane** is what a human uses in the
panel: users, organizations, roles, members, keys. The **customer plane** is
what a developer's own product uses: contacts, identities, the federated
boot and the two proofs of an address.
Every error answers the same envelope — `{"error": {"code", "message"}}`.
The `code` is a stable contract to branch on; the `message` is for a person
and may change.
servers:
- url: '{baseUrl}'
description: The API host.
variables:
baseUrl:
default: https://api.userkit.dev
description: Base URL of the API, no trailing slash.
security:
- sessionToken: []
tags:
- name: Gamification
description: >-
Points, levels and badges: the acts your product wants repeated, written
down as rules, and what each of your own users has accumulated by doing
them. A rule pays when the fact it names lands — there is no endpoint your
users can call that moves a balance, and there is not going to be one.
- name: Authentication
description: >-
Public sign-up, sign-in, two-factor and password recovery for staff
accounts.
- name: Session
description: >-
The active session: who the caller is, which organization they are in, and
signing out.
- name: Account
description: The caller's own account — profile, password, sessions, avatar.
- name: Two-factor
description: >-
TOTP setup, activation and recovery codes. Returns 501 when two-factor is
unavailable on the server.
- name: Organizations
description: The organizations a user belongs to, and the active one.
- name: Environments
description: >-
The live and test environments seeded with every organization, and their
identity settings.
- name: Members
description: Memberships and invitations.
- name: Roles
description: Roles and the permission catalogue they draw from.
- name: Audit log
description: >-
What staff did inside an organization. Append-only, and read behind its
own permission.
- name: API keys
description: Secret keys (`uk_sk_…`) and publishable keys (`uk_pk_…`).
- name: Contacts (staff session)
description: >-
The staff view of the customer plane, opened by a staff session. Reads
take `?environment=` as an explicit view parameter.
- name: Contacts (API key)
description: >-
The machine surface, authenticated by an API key. The environment is the
key's environment and cannot be named by the caller.
- name: Customer plane
description: >-
Called from the developer's own pages with a publishable key: boot, the
two proofs of an address (magic link, email code), and the contact's own
session.
- name: Customer teams
description: >-
A customer is a team. Its roster, its invitations and the roles held
inside it, administered by the contact's own session. `owner` and `member`
always exist; the rest of the vocabulary is the organization's own — see
Customer roles. The active customer travels in `X-Customer-Id`.
- name: Customer roles
description: >-
The vocabulary of roles inside your customers, defined per environment. A
customer used to be two shapes — the person who administers it and
everybody else — which is what `owner` and `member` are, and they are
still seeded into every environment and cannot be deleted. Beyond them you
define your own: a school has a director, a secretary, a teacher and a
student, and none of that fits a boolean.
A role carries permissions from **two vocabularies in one list**.
Permissions beginning with `$` are UserKit's own and are the only ones we
evaluate — `$team.manage` administers the roster, `$billing.manage` the
money, `$keys.manage` the team's API keys. Everything else is yours: we
store it, we hand it back on the contact's session and in the
`customer_permissions` claim of their JWT, and we never read it. That is
the point — your backend gates `grades:write` offline, and adding a role
never means editing your gate.
Reading is `customers:read`, writing `customers:write`.
- name: Webhooks
description: >-
Outbound webhooks: endpoints, the published event catalogue, the delivery
log, replay and test sends. Never gated by a plan — webhooks are a
developer primitive.
- name: Catalogue
description: >-
The plans, prices and features **you** sell to your own customers. Per
environment, a price per currency, and `recurring` or `one_time`. Distinct
from the plan you are on with UserKit, which is `GET
/v1/organization/entitlements`.
- name: Subscriptions
description: >-
What one of **your** customers is paying you, mirrored from the gateway
that charges them. The gateway is the truth about money — it holds the
schedule, runs the retries and decides what a proration is worth — so
these routes ask it to change something and answer with what it then said.
`provider_synced_at` is how stale the copy admits to being.
- name: Provider webhooks
description: >-
Where a payment provider delivers to. Not a surface you call — it is a URL
you paste into the provider's dashboard, which is why it sits outside
`/v1`: a version bump must never mean editing a setting in somebody else's
product. Signed with the secret of the connection named in the path, and
safe to retry.
- name: Entitlements
description: >-
What one of **your** customers may do, resolved: the plan their
subscription carries, plus the overrides you promised them on top. This is
the read your own gate calls, so it is cached and answers in one round
trip. It is a different question from `GET /v1/organization/entitlements`,
which is the plan **you** are on with UserKit — two catalogues, same word,
different money.
- name: Credits
description: >-
How much of a `credit` feature one of **your** customers still holds. The
balance is an append-only ledger folded on demand — grants arrive from
paid invoices, usage spends against it (`POST /v1/usage`, fail closed),
unused credits expire oldest-first, and a support correction is a new
signed line rather than an edit. Whether a balance may go below zero, and
how far, is the plan's `overdraft_limit`.
- name: Customer API keys
description: >-
Keys **your customers** issue (`uk_ck_live_…` / `uk_ck_test_…`) so your
own metered surface can be called per key. An owner of a customer team
mints them from their session; your backend treats the string as data and
resolves it with `POST /v1/customer-keys/verify` (or passes it as
`customer_key` to `POST /v1/usage`). A customer key never authenticates
against this API.
- name: Customer webhooks
description: >-
Webhook endpoints **your customers** register from the portal, hearing the
events *you* tracked about their team — `POST /v1/track` lines carrying
their `customer_id`, delivered under your own event names. Administered
under `$webhooks.manage` (the seeded `owner` role holds it), signed and
retried exactly like your own endpoints, and gated by your plan:
registering answers `webhooks_not_available` on a plan without the
capability, and a downgrade stops deliveries without deleting anything.
- name: Pricing
description: >-
The public read of what you sell: live plans and prices, addressed by
publishable key, cacheable like JWKS. What a `` renders,
and the offer the customer's own checkout sells from.
- name: Customer billing
description: >-
The customer's **own** view of what their team pays, from their session:
the subscription, the invoices, and the self-serve acts — checkout, plan
change, cancel, resume, the gateway's portal. Reads are for every member;
the money acts are owner-only, because spending the team's money is
administering the team.
- name: Support
description: >-
The support inbox. A conversation is opened by **your customer** — from
the chat widget, or by an inbound email — and staff receive it: there is
deliberately no staff-side create. Conversations live in an environment
(their subject is a contact); tags and saved replies are the
organization's own vocabulary and take no environment. `support:read` and
`support:write` gate the staff surface, and every seeded role holds both —
the support agent is the archetypal member seat.
- name: Help center
description: >-
The articles you publish so a conversation does not have to happen.
Organization-scoped — the product does not differ between live and test
the way its contacts do — and versioned append-only: saving creates the
next version, publishing points the public page at one of them, and
restoring is publishing an old one. The editor rides the support
permissions; the published side is public, addressed by your publishable
key, and cacheable.
- name: Segments
description: >-
Audiences, defined declaratively over contact attributes, plan, events and
activity. One definition compiles into two evaluators that must agree — a
query over the environment and an in-process match for one contact — so
the count on a screen and the decision made about one person come from the
same sentence. Reading is `customers:read` (a segment is a filtered list
of contacts); writing is `segments:manage`, because one definition decides
who is mailed, surveyed and shown an unreleased feature at once.
- name: Feature flags
description: >-
Release switches the tenant's own product reads. A flag is aimed at a
**segment** and never at a filter of its own, so the audience a rollout
uses is the audience a survey and a changelog post can use. Two reads
serve it: `POST /v1/boot` decides every flag for the person in the round
trip the session already cost, and `GET /v1/flags/{publishable_key}` is a
public, cacheable document that carries only the switch — polled on a
fifteen-second clock and applied over whatever the page booted with. Staff
CRUD is `flags:manage`.
- name: Onboarding
description: >-
Checklists the widget renders for your own users, and the funnel behind
them. A step is satisfied by a **fact having happened** or by an
**entitlement being held** — there is no endpoint that marks one done, by
construction, because a checklist whose completion is a button is a
measure of who pressed the button. Event steps are written by a bus
consumer and are what the funnel counts; entitlement steps are decided on
the read against the team the request names, and nothing is stored for
them. Staff CRUD and the funnel are `engagement:manage`, the permission
the changelog and surveys share.
- name: Surveys
description: >-
NPS and one-question surveys, asked in-app. A survey is aimed at a
**segment** or at everybody, fires on a trigger (a fact you named,
entering that audience, or N days after somebody signed up) and is held
back by a **per-contact cooldown** — the window is per person rather than
per survey, which is what makes "nobody is surveyed twice a week" true
across every survey you run. Delivery is in-app: `GET
/v1/contact/surveys/pending` is what the widget reads and `POST
/v1/contact/surveys/{id}/response` is the answer, which announces
`survey.response_recorded` to your webhooks. Staff CRUD and the results
are `engagement:manage`, the permission onboarding and the changelog
share.
- name: Changelog
description: >-
What you shipped, said once. A post is written as a draft, aimed at a
**segment** or at everybody, and published by an act of its own —
publishing is what puts it in a cacheable public document and announces
`changelog_post.published` to your webhooks, so it is a call you make on
purpose rather than a field on an edit. Two reads serve it: `GET
/v1/changelog/{publishable_key}` is the public release page and carries
the posts aimed at nobody in particular; `GET /v1/contact/changelog` is
the same list for one signed-in person, with the targeting honoured and
their read state on it. Staff CRUD is `engagement:manage`, the permission
onboarding and surveys share.
- name: Banners
description: >-
Messages you put on your own users' screens — a strip at the top of the
dashboard, a notice in the billing settings, a picture you designed. A
banner names a **slot**, which is a place your own developer left room for
with ``; nothing is injected into your
layout, because the only place a third party may draw is one the page
owner declared. It is aimed at a **segment** or at everybody, bounded by
an optional window, and only **one banner per slot** is ever returned —
highest priority wins, decided in the database so every client gets the
same answer. Two kinds: `text` (title, body, icon, tone, button), drawn by
the widget in your palette, and `image`, a picture you made and optionally
a link. `GET /v1/contact/banners` is what the widget reads and `POST
/v1/contact/banners/{id}/dismiss` is the close button. Staff CRUD is
`engagement:manage`, the permission onboarding, the changelog and surveys
share.
- name: Legal
description: >-
The terms your own customers agree to — terms of service, a privacy
policy, a code of conduct — and the record of who agreed to which words. A
**document** is a name, an address (`slug`) and a rule about whether
agreeing is required; a **version** is the text, and it is frozen the
moment it is published, because an acceptance that pointed at an editable
body would prove nothing. Publishing may be dated ahead, which is what a
thirty-day notice is: the version before it stays in force until then. A
new version asks everybody again only when it says `requires_reacceptance`
— a corrected typo does not, a new arbitration clause does. `GET
/v1/legal/{publishable_key}` is public and cacheable, because a sign-up
form has to render the link before there is any session. `required`
refuses nothing — there is no sign-up door of UserKit's for it to refuse
at — and is reported as `blocking` wherever outstanding agreements are
read; what an outstanding agreement does is your product's decision. It
never refuses an ordinary API call, and `POST /v1/contact/token` in
particular — publishing new terms must mean "everybody is asked", never
"everybody is logged out". Staff CRUD is `legal:manage`.
- name: Feedback
description: >-
A feedback board and a public roadmap. Your users ask for things, vote on
each other's requests and read what you answered; you triage, merge the
duplicates and move a post to `planned`, `shipped` or `declined`. The part
a separate feedback tool cannot do is the ranking: `GET
/v1/organization/feedback?currency=BRL` weights every post by the
**revenue of the distinct customers behind its voters**, so a team of five
is worth its revenue once rather than five votes. That number exists on
the staff read and nowhere else — the public board says how many people
asked, never who pays. Reading is `feedback:read` (owner, admin **and**
member, because triage is support work); answering is `feedback:write`.
- name: Notifications
description: >-
Consent for the mail this platform sends your own users, and the
unsubscribe link that changes it.
Three categories — `marketing`, `product_news` and `surveys` — and every
one of them is something a person can switch off. **Transactional mail is
not one of them, and there is no value that names it.** A receipt, a
dunning notice, a verification link and a password reset keep arriving
after somebody unsubscribes from everything, because the absence of the
category is what guarantees no screen and no bulk update can produce a
person who cannot reset their own password.
Consent is honoured at the **send funnel** rather than by whoever composes
the message, in the same statement that records the delivery — so a
message this person switched off is a message that is never composed, not
one that is filtered afterwards. Every non-transactional message carries
the unsubscribe link in its footer and the `List-Unsubscribe` /
`List-Unsubscribe-Post` header pair on its envelope; no transactional
message carries either.
- name: Messaging
description: >-
The message templates outbound campaigns send: a subject, a body, a
channel and the **category** the recipient can switch off.
The subject and the body are Go `text/template`, compiled **when you
save** — a template naming a field the message context does not carry is
refused with the field named, never stored to fail per recipient in a job
at three in the morning. The context is closed on purpose: `Contact`,
`Customer`, `Plan` and `Entitlements`, and nothing else. Whatever a
template can reach is reachable by whoever can write one.
The category lives on the template rather than on whatever sends it,
because a category is a statement about what a message *says*, and the
template is the only object here that knows what it says. A campaign
inherits it. `messaging:manage` covers the whole surface, reads included —
an unsent price change is not something a wider permission should be able
to read.
- name: Campaigns
description: >-
The object that reaches out: an audience, a trigger, a sequence and a cap.
The audience is always a **segment** — there is no filter of a campaign's
own, because an audience defined twice can be previewed one way and mailed
another. The words are a **message template**, and the campaign inherits
the template's category rather than choosing one. The trigger is one of
four: a one-shot to whoever is in the audience now, a fact of a named
type, entering the audience, or N days from a timestamp on the contact.
Two limits hold at once and they are different promises.
`frequency_cap_days` is how long **this** campaign waits before reaching
the same person again; a 24-hour cooldown across **every** campaign of the
environment sits behind it, so somebody who trips three rules in one hour
receives one message. Neither applies to the later steps of a sequence
already begun — a cooldown that broke a sequence in half would be a setup
that works in test and truncates in production.
A contact who has switched the template's category off is recorded as
**suppressed with the reason**, which is what lets support answer "why
didn't they get it". Writing a campaign is free; **arming** one is what a
plan gates.
- name: In-app notifications
description: >-
The message that lands inside your product rather than in an inbox: "your
export is ready", "the invoice failed", "someone mentioned you".
Your backend posts one over `uk_sk_…` and the person reads it from their
own session. It is **transactional by construction** — the request carries
no category and there is no field that could carry one, so an in-app
notification is not something anybody can unsubscribe from, in the same
way a receipt is not. That is not a policy this endpoint applies; it is
the only value the write can produce.
The write inherits the machine surface's two promises by living on it: an
`Idempotency-Key` replays the first response rather than telling somebody
the same thing twice, and the per-key rate limit counts the call. The
recipient is named by `contact_id` or by your own `external_id` — one of
the two, never both, because a request naming two people is a request we
would have to guess about.
- name: MCP
description: >-
One endpoint an AI agent's client connects to, so "how many people signed
up this week" is answered where the question is asked. Authenticated with
an API key, which is also what fixes the environment — no tool takes one
as an argument. Every tool is a READ: nothing here creates, changes or
deletes anything, and nothing answers with a credential or with the staff
audit log. Outside `/v1` because the URL lives in a configuration file
rather than in your code.
- name: Analytics
description: >-
The staff read of what happened inside your product: the event explorer,
daily counts, saved queries and funnels. Everything here sits behind
`analytics:read` — owner and admin by default, because Phase 4's
dashboards put revenue on the same screens as event counts. The write path
is `POST /v1/events` and the platform's own auth facts; no staff session
reaches it.
- name: Alerts
description: >-
Where your organization's bad news gets delivered: Slack, Discord or
email. Everything else here is pull — you open a screen and the number is
there — and this is the push half, for the five facts nobody opens a
screen to discover: the contact meter at 80% and 100%, an environment out
of its email allowance, a webhook endpoint turned off after sustained
failure, a payment gateway that stopped answering, and a customer's
payment being declined.
The five are **fixed**. There is no rule to configure and no threshold to
set — what fires is decided by the code that publishes each fact, and a
second place to re-decide it would be a place that disagrees. What you
configure is the destination.
The destination is stored encrypted and is never read back: a Slack
incoming webhook is a credential, and whoever holds it writes into that
channel. Responses carry `destination_hint` — the host for a chat hook,
the address for an email. Gated by `alerts:manage`, which only `owner`
holds by default.
- name: Referrals
description: >-
Your own users bringing you other users, and what you owe them for it. A
code carries its terms (a share in basis points, or a flat bounty),
`?ref=CODE` is captured by the SDK as first-touch attribution and recorded
at the referred person's first identification, and a paid invoice appends
a commission line. First touch is immutable — whoever referred somebody
referred them, and a later link cannot take the commission — and a refund
appends a negative line rather than erasing the positive one. Payouts are
manual: this surface says what is owed and nothing here transfers money.
paths:
/v1/contact/gamification:
get:
tags:
- Gamification
summary: This person's points, level and badges
description: >-
What the widget renders for the person holding the page: their balance,
where it places them, and their shelf.
**Nothing here writes, and there is no endpoint that does.** A point is
a fact landing — the same rule that gives an onboarding step no "mark as
done". The moment a page can ask for points, the page's network tab is
the game. Your own backend can grant one with `POST /v1/points`, which
is a program you control.
An anonymous session is answered `200` with zeros rather than `401`: the
widget runs on your landing page, and nothing pays a visitor. What
somebody earns after they sign in follows them — the
anonymous-to-identified merge moves the ledger, so points earned in the
session that became an account are not lost.
`level` and `next_level` are `null` when no level is defined or when
there is nothing above — draw the progress bar off `points_to_next`,
which is `null` at the top.
A badge's CONDITION deliberately does not travel. Handing somebody
"unlock at 40 invites" is handing them the rule to farm, and a hidden
badge would stop being a surprise the moment anybody opened the network
tab.
A LEVEL's conditions travel and a BADGE's do not, on the same response.
It is the same principle twice: a badge is a surprise you are entitled
to keep — handing somebody "unlock at 40 invites" hands them the rule to
farm — while a rung is a goal your product is ASKING them to reach, and
a progress bar that cannot say "2 courses to go" is a bar filling for
reasons nobody can act on. The one thing withheld is the NAME of an
audience.
operationId: getContactGamification
responses:
'200':
description: The standing.
content:
application/json:
schema:
type: object
properties:
balance:
type: integer
description: >-
The sum of their ledger. Zero for somebody who has earned
nothing, and for an anonymous session.
level:
type: object
nullable: true
properties:
name:
type: string
rank:
type: integer
description: Its place in the ladder.
threshold:
type: integer
nullable: true
description: >-
The rung's POINTS condition, and `null` when it states
none. A rung asking only for four courses has no such
number rather than a zero.
icon:
type: string
nullable: true
description: >-
The rung they are on, or `null`. `null` is the ordinary
case rather than an error — most environments define no
levels — and it must not be rendered as level zero.
next_level:
type: object
nullable: true
properties:
name:
type: string
rank:
type: integer
description: Its place in the ladder.
threshold:
type: integer
nullable: true
description: >-
The rung's POINTS condition, and `null` when it states
none. A rung asking only for four courses has no such
number rather than a zero.
icon:
type: string
nullable: true
requirements:
type: array
description: >-
What this rung is still waiting for, one entry per
condition. Present on `next_level` only. A progress
bar drawn off `points_to_next` alone fills and
promotes nobody when the rung also wants four courses
— this is the honest version.
items:
type: object
properties:
kind:
type: string
enum:
- points
- metric
- rule_awards
- achievement
- segment
met:
type: boolean
have:
type: integer
nullable: true
description: >-
What they have, for the three kinds that count.
`null` for a badge or an audience, which are
held or not.
need:
type: integer
nullable: true
target:
type: string
nullable: true
description: >-
The name of what is being asked for, so you can
write "2 courses to go". Always `null` for a
`segment` requirement: an audience name is your
own internal copy about your users and was never
written for them to read.
unit:
type: string
nullable: true
description: >-
The lowest rung above the current one that is not yet
satisfied, or `null` at the top, with `requirements`
saying what it is waiting for.
points_to_next:
type: integer
nullable: true
description: >-
The POINTS gap to `next_level`, and zero when the next
rung asks nothing about points. Kept for widgets built
before metrics existed; `next_level.requirements` is what
a bar should be drawn from now.
achievements:
type: array
description: >-
The shelf: every active badge that is not hidden, plus any
hidden one they hold. Earned first, then the ones still to
earn.
items:
type: object
properties:
key:
type: string
name:
type: string
description:
type: string
nullable: true
icon:
type: string
nullable: true
unlocked_at:
type: string
format: date-time
nullable: true
description: >-
`null` for a badge still to earn — the widget draws
the same card and greys it.
metrics:
type: array
description: >-
What this person has of each tally the environment counts,
including the ones at zero — the badge shelf's own rule: a
widget drawing "0 of 4 courses" is showing somebody a
goal, while an absent key looks like a bug.
items:
type: object
properties:
key:
type: string
name:
type: string
unit:
type: string
nullable: true
icon:
type: string
nullable: true
value:
type: integer
description: >-
Their tally, folded from the same ledger the balance
is.
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
security:
- contactToken: []
components:
responses:
Unauthorized:
description: >-
`unauthorized` — missing, malformed, expired or revoked credential, and
nothing else: it says the credential is gone, so a client is right to
discard it and sign in again. A well-formed credential from the wrong
family says so: "this endpoint expects a staff session token, not an
organization API key". A LIVE staff session aimed at an organization it
is not a member of is `not_a_member` (403), never this.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: >-
`rate_limited` — too many requests. `Retry-After` carries the window in
seconds.
The counters are shared across instances. When that store cannot be
reached each instance counts on its own instead: the limits get looser,
never absent.
headers:
Retry-After:
schema:
type: integer
description: Seconds until the window resets.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
description: Every error in this API answers this envelope.
properties:
error:
type: object
properties:
code:
type: string
description: Stable. Branch on this.
message:
type: string
description: For a person. May change.
required:
- code
- message
required:
- error
example:
error:
code: forbidden
message: your role does not allow this action
securitySchemes:
sessionToken:
type: http
scheme: bearer
description: >-
A staff session token, `uk_st_…`. Minted by sign-up, sign-in or the
two-factor exchange. Only a 401 means it is spent; `not_a_member` (403)
is about the organization named in `X-Organization-Id` and leaves the
token good for the others.
contactToken:
type: http
scheme: bearer
description: >-
A contact session token, `uk_ct_…`. Belongs to one of the developer's
own users, and reads only that user's data.
````