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:
| Type | What it is | Answered by |
|---|---|---|
approval | A yes/no decision with up to 4 actions. Default actions are Approve and Deny | Tapping an action, optionally with a comment |
question | One to 12 typed fields: text, textarea, choice, multichoice, number, date, toggle | Submitting the form |
preview | A rendered result: image, video, audio, PDF, Markdown, web page, document, 3D model, gallery or folder | Opening it; optional review actions such as Looks good |
status | Progress with a bar and steps, shown as a Live Activity | The agent updates it; the owner can cancel |
note | A short message, no answer needed | Nothing |
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:
| Source | Shows |
|---|---|
metric | One number with its delta and sparkline |
metrics | Up to four small numbers |
cards | A live list or stack of cards matching a filter (type, state, class glob, tag, project, thread) |
card | One pinned card |
text | A Markdown note the agent wrote |
link | A 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.
| Scope | Prefix | Can |
|---|---|---|
write | afk_w_ | Create, patch and withdraw its project's cards, wait for answers, write metrics, upload media |
board | afk_b_ | Everything in write, plus create, replace and patch boards and tiles |
delegate | afk_d_ | Everything in board, plus answer cards in the classes you list, with a reason |
admin | afk_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.
| Effect | Does |
|---|---|
auto_approve | Answers the card at once as the rule, with no notification. Choose the action with action |
silent | Delivers the card to the inbox without notifying you |
interrupt | Always rings, even if the card would normally be quiet |
expire_default | Lets 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.