> ## 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.
# Create an onboarding checklist
> Requires `engagement:manage`. Names are unique per environment; a duplicate answers `409 checklist_exists`.
`active` defaults to **false**: a checklist exists while its steps are being written, and creating one never starts measuring anybody. That matters more here than it does for a flag, because **a checklist counts from the moment it is turned on** — a fact that happened before it existed does not count. The bus is not an event store, so there is no history to replay, and a rule that applied to some steps and not others would produce a funnel whose two numbers cannot be compared.
`segment_id` is who it is for, or `null` for everybody, and it must name a segment of the same environment. It decides who is **shown** the checklist, not who is recorded against it: somebody who enters the audience next week does not start from zero having already done the work.
## OpenAPI
````yaml /api-reference/openapi.json post /v1/organization/checklists
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/organization/checklists:
post:
tags:
- Onboarding
summary: Create an onboarding checklist
description: >-
Requires `engagement:manage`. Names are unique per environment; a
duplicate answers `409 checklist_exists`.
`active` defaults to **false**: a checklist exists while its steps are
being written, and creating one never starts measuring anybody. That
matters more here than it does for a flag, because **a checklist counts
from the moment it is turned on** — a fact that happened before it
existed does not count. The bus is not an event store, so there is no
history to replay, and a rule that applied to some steps and not others
would produce a funnel whose two numbers cannot be compared.
`segment_id` is who it is for, or `null` for everybody, and it must name
a segment of the same environment. It decides who is **shown** the
checklist, not who is recorded against it: somebody who enters the
audience next week does not start from zero having already done the
work.
operationId: createChecklist
parameters:
- $ref: '#/components/parameters/OrganizationHeader'
- $ref: '#/components/parameters/EnvironmentQuery'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
maxLength: 120
active:
type: boolean
default: false
segment_id:
type: string
format: uuid
nullable: true
unlocks_after:
type: string
format: uuid
nullable: true
description: >-
The checklist this one waits on. `null` clears it. Same
environment, and a cycle is a `400`.
selectable:
type: boolean
description: >-
Whether this one is a choice the person makes rather than a
decision the segment makes for them.
snooze_days:
type: integer
minimum: 0
maximum: 365
default: 7
description: >-
How many **days** a close holds for. After that the
checklist comes back.
`0` means a close lasts forever — the right value for a
checklist that really is a one-time offer, and the behaviour
every checklist had before this field existed.
Seven by default, because pressing X on a setup guide almost
never means "never help me again"; it means "not now".
Changing this never moves a snooze already running: the end
is computed when somebody closes the card and stored, so the
promise made to that person is the one that is kept.
hint_pending:
type: string
nullable: true
maxLength: 200
description: >-
What it says on hover while it is NOT done — a reason or an
instruction the title has no room for.
Two texts and not one because the same line means different
things before and after: pending, the useful sentence is an
instruction; done, an instruction is noise and what is
useful is what it bought. A single field would force a
sentence that is wrong half the time.
hint_done:
type: string
nullable: true
maxLength: 200
description: >-
What it says on hover once it IS done. Null is the common
case and reads correctly — nothing on hover about a thing
somebody already did.
hint_locked:
type: string
nullable: true
maxLength: 200
description: >-
What the heading says on hover while the checklist is LOCKED
— the third state a heading has and a step does not.
The widget already shows a padlock and the name of what it
waits on, and a name is a door rather than a reason. This is
the reason.
responses:
'201':
description: The checklist, with no steps yet.
content:
application/json:
schema:
type: object
properties:
checklist:
$ref: '#/components/schemas/Checklist'
'400':
description: >-
A missing name (`invalid_request`), an unknown segment
(`unknown_segment`), or a segment belonging to another environment
(`segment_environment_mismatch`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
description: >-
A checklist with this name already exists in this environment
(`checklist_exists`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
parameters:
OrganizationHeader:
name: X-Organization-Id
in: header
required: false
schema:
type: string
description: >-
The organization the caller is acting on — the `org_…` code that appears
in the panel URL. It *identifies*; the membership JOIN is what
*authorizes*, so a forged code reads nothing: the answer is
`not_a_member` (403), which does not mean the session is over. Absent,
the session's default organization answers, or — if that membership was
revoked while the session was open — any other one the caller still
holds.
EnvironmentQuery:
name: environment
in: query
required: false
schema:
type: string
enum:
- live
- test
default: live
description: >-
Which environment to act in. A view parameter, valid only on the staff
surface — a machine credential never chooses its environment, it is
resolved from the key.
schemas:
Checklist:
type: object
description: >-
An onboarding list, aimed at a segment and never at a filter of its own.
It counts from the moment it is turned on: a fact that happened before
it existed does not count, because the bus is not an event store and a
rule that applied to some steps and not others would produce a funnel
whose numbers cannot be compared.
properties:
id:
type: string
format: uuid
environment_id:
type: string
format: uuid
name:
type: string
active:
type: boolean
description: >-
Whether the widget renders it and whether progress is recorded
against it. The reversible off switch — there is no archive here,
because nothing outside this API names a checklist.
dismissals:
type: integer
description: >-
How many people have ever closed this checklist without finishing
it. Present on the list read.
The number completion cannot give: a checklist nobody completes
might be one nobody sees, while one people close on sight is a
different problem with a different fix. Closing is per checklist —
dismissing this one says nothing about your others, nor about the
ones you have not created yet.
Read it against `hidden`. This is the history; `hidden` is the state
now.
hidden:
type: integer
description: >-
How many people it is closed FOR RIGHT NOW. Present on the list
read.
On a checklist that snoozes, this sits below `dismissals` — the
difference is the people whose close has expired and who are seeing
it again. The two being **equal** is the signal worth acting on:
everybody who closed it did so recently, which is what a card people
are actively pushing away looks like.
segment_id:
type: string
format: uuid
nullable: true
description: >-
The audience, or `null` for everybody. It decides who is shown the
list, not who is recorded against it.
unlocks_after:
type: string
format: uuid
nullable: true
description: >-
The checklist this one waits on, or `null` for one that waits on
nothing. Same environment only, and a cycle is refused — two lists
waiting on each other is a pair neither of which can ever open.
selectable:
type: boolean
description: >-
Whether the PERSON chooses this one, from the guide's modal, rather
than the tenant deciding for them by segment. Default false: the
segment still decides what is offered, and this hands the last step
over. It changes nothing about what satisfies a step.
snooze_days:
type: integer
minimum: 0
maximum: 365
default: 7
description: >-
How many **days** a close holds for. After that the checklist comes
back.
`0` means a close lasts forever — the right value for a checklist
that really is a one-time offer, and the behaviour every checklist
had before this field existed.
Seven by default, because pressing X on a setup guide almost never
means "never help me again"; it means "not now". Changing this never
moves a snooze already running: the end is computed when somebody
closes the card and stored, so the promise made to that person is
the one that is kept.
hint_pending:
type: string
nullable: true
maxLength: 200
description: >-
What the heading says on hover while it is NOT done — a reason or an
instruction the title has no room for.
Two texts and not one because the same line means different things
before and after: pending, the useful sentence is an instruction;
done, an instruction is noise and what is useful is what it bought.
A single field would force a sentence that is wrong half the time.
hint_done:
type: string
nullable: true
maxLength: 200
description: >-
What the heading says on hover once it IS done. Null is the common
case and reads correctly — nothing on hover about a thing somebody
already did.
hint_locked:
type: string
nullable: true
maxLength: 200
description: >-
What the heading says on hover while the checklist is LOCKED — the
third state a heading has and a step does not.
The widget already shows a padlock and the name of what it waits on,
and a name is a door rather than a reason. This is the reason.
created_by:
type: string
format: uuid
nullable: true
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
steps:
type: array
items:
$ref: '#/components/schemas/ChecklistStep'
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
ChecklistStep:
type: object
description: >-
One line of the list. `kind` decides which of `event_type` and
`feature_key` carries the rule; the other is always null. `action_url`
and `action_label` are what happens when somebody clicks it, and neither
has anything to do with what satisfies it.
properties:
id:
type: string
format: uuid
key:
type: string
description: What your own code addresses the step by. Unique per checklist.
title:
type: string
kind:
type: string
enum:
- event
- product_event
- entitlement
description: >-
What satisfies the step.
`event` — a fact **we** publish about a contact. A closed list: a
name that is not on it is refused, so this kind cannot become a step
that never goes green.
`product_event` — an event **your** product sends through `track()`.
Your vocabulary is open, so a name cannot be refused for not
existing; only its shape is checked, and the step comes back with
`sightings` so a typo is visible. This kind carries a weaker
guarantee than the other two: analytics drops events under load and
our own bus does not.
`entitlement` — a feature the contact's team holds, decided on every
read rather than recorded.
event_type:
type: string
nullable: true
description: >-
Required for both event kinds. For `event`, one of the contact facts
this system publishes (see `event_types` on the checklist read). For
`product_event`, the exact name your product sends through
`track()`.
feature_key:
type: string
nullable: true
description: The feature from your own catalogue an entitlement step asks about.
action_url:
type: string
nullable: true
description: >-
Where the line sends somebody when they click it: a path starting
with `/` (your own app) or an absolute `http(s)` URL. The
protocol-relative form is refused, and so is anything else — this
address is written by you and clicked inside your own page.
**Clicking never satisfies a step.** `kind` decides that and nothing
else does: a link is the door, not the proof somebody walked through
it.
action_label:
type: string
nullable: true
description: >-
The word on the control. Without it the step's own title becomes the
link, which is usually right; set it when the title is a state
("Domain verified") and the action is a verb ("Verify").
Set **alone**, with no `action_url`, it means the action is not a
navigation — your own page handles the click through the SDK's
`onStepAction`. A step like that renders a control that does nothing
on a page which never wired that callback.
hint_pending:
type: string
nullable: true
maxLength: 200
description: >-
What the line says on hover while it is NOT done — a reason or an
instruction the title has no room for.
Two texts and not one because the same line means different things
before and after: pending, the useful sentence is an instruction;
done, an instruction is noise and what is useful is what it bought.
A single field would force a sentence that is wrong half the time.
hint_done:
type: string
nullable: true
maxLength: 200
description: >-
What the line says on hover once it IS done. Null is the common case
and reads correctly — nothing on hover about a thing somebody
already did.
position:
type: integer
sightings:
type: integer
description: >-
`product_event` steps only. How often this environment has seen that
name in the last 90 days. **Zero is the warning**: your event
vocabulary is open, so a name that does not exist cannot be refused,
and a step nobody has ever sent is almost always a typo.
last_seen:
type: string
format: date-time
nullable: true
description: >-
`product_event` steps only. When that name was last seen, or `null`
for never.
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'
Forbidden:
description: >-
`forbidden` — your role does not allow this action. On any route taking
a staff session, `not_a_member` is the other 403: the session is valid
and the organization named in `X-Organization-Id` is not one you belong
to. Same answer for an organization that does not exist and for a code
that is not even shaped like one — the refusal is not a directory.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
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.
````