Concepts#

A handful of objects explain the whole product.

Cards#

A card is one thing an agent wants you to look at. There are five types:

TypeWhat it isAnswered by
approvalA yes/no decision with up to 4 actions. Default actions are Approve and DenyTapping an action, optionally with a comment
questionOne to 12 typed fields: text, textarea, choice, multichoice, number, date, toggleSubmitting the form
previewA rendered result: image, video, audio, PDF, Markdown, web page, document, 3D model, gallery or folderOpening it; optional review actions such as Looks good
statusProgress with a bar and steps, shown as a Live ActivityThe agent updates it; the owner can cancel
noteA short message, no answer neededNothing

A card has a state: open, answered, expired, withdrawn or done. Agents can update an open card (PATCH), withdraw it, or give it a ttl and an on_expire action. Cards with the same thread stack together, and a dedupe_key updates the open card with that key instead of creating a second one. Send an Idempotency-Key header to make retries safe.

The class field is a dotted name such as deploy.production. Rules and delegate keys match on it, so choose classes you can talk about in a sentence.

Boards and tiles#

A board is a screen of tiles in a flow layout. Each tile has a size (small 1x1, medium 2x1, large 2x2), a tint, an icon and exactly one source:

SourceShows
metricOne number with its delta and sparkline
metricsUp to four small numbers
cardsA live list or stack of cards matching a filter (type, state, class glob, tag, project, thread)
cardOne pinned card
textA Markdown note the agent wrote
linkA shortcut

Boards are programmable: a key with the board scope can create and replace boards and tiles. When you move or resize a tile yourself, it is marked pinned_by_user and API writes leave it alone, so you and your agents can share one screen. A new account starts with a "Home" board.

Metrics#

A metric is a named number such as youtube.subscribers. PUT /metrics/{name} writes one point; descriptive fields (label, unit, format, better, goal) are upserted when present. Frame computes the change against 24 hours earlier and colours it by better (up, down or none). At most one point per minute is stored, kept for your plan's history.

Projects#

A project groups keys, cards and an optional webhook. Every account starts with a project called Default. Use one project per product, team or environment so that a key can only see its own cards.

Keys and scopes#

Agents authenticate with an API key in the Authorization: Bearer header. The prefix tells you the scope.

ScopePrefixCan
writeafk_w_Create, patch and withdraw its project's cards, wait for answers, write metrics, upload media
boardafk_b_Everything in write, plus create, replace and patch boards and tiles
delegateafk_d_Everything in board, plus answer cards in the classes you list, with a reason
adminafk_a_Everything on the account except billing: projects, keys, rules, webhooks

Keys can expire and can be limited to IP ranges (allowed_ips, CIDR). The secret is shown once and stored only as a SHA-256 hash. The app itself uses session tokens (afs_), not keys.

Rules#

A rule matches a card class with a glob (deploy.staging, cost.*) and applies an effect. The first enabled rule that matches, in creation order, wins.

EffectDoes
auto_approveAnswers the card at once as the rule, with no notification. Choose the action with action
silentDelivers the card to the inbox without notifying you
interruptAlways rings, even if the card would normally be quiet
expire_defaultLets the card expire with its on_expire default

Rules are a Pro feature. Every automatic answer is recorded on the card with the rule's name, so you can always see why something was approved.

Delegate keys#

Sometimes you want an agent to answer on your behalf, for instance a supervisor agent that signs off on routine work. A delegate key may call POST /cards/{id}/respond only for cards whose class matches one of its delegate_classes, and must send a reason, which is shown on the card with the key's name as the actor. Cards outside those classes still need you.

Notifications, the interrupt budget and quiet hours#

For each new card the server decides between three outcomes: ring (sound, time-sensitive), quiet (delivered without sound) and none (inbox only). In order: a matching rule decides first; notify: "silent" means none; priority: "urgent" from a board, delegate or admin key rings regardless of budget; approvals and questions ring, previews are quiet, status cards and notes are none; quiet hours turn a ring into quiet (except urgent); and after your interrupt budget (rings per day, default 5) further rings become quiet. The lock screen shows the title only.

Devices and sync#

Every device you sign in is a device on the same account. Pair another one by showing a six-digit code on a signed-in device and entering it on the new one (or on the web client). A card answered on one device clears everywhere within a moment, and the app reconnects to a realtime stream and refetches open cards after any gap. Boards, rules and settings live on the server, so every device shows the same thing.