API reference#
A JSON REST API over HTTPS. Everything the apps, the CLI, the SDKs and the MCP server do goes through it.
Base URL: https://api.agentsframe.com/v1. Send Authorization: Bearer <token> and, for bodies, Content-Type: application/json. Keys and shapes are described below; the shapes are generated from the contract in the repository (contract/types.ts), so they cannot drift from the server.
curl https://api.agentsframe.com/v1/me -H "Authorization: Bearer $AGENTSFRAME_KEY"Conventions#
- JSON, UTF-8,
snake_casekeys, timestamps in RFC 3339 UTC (2026-11-16T18:00:00.000Z). - Ids are prefixed strings:
acc_account,prj_project,crd_card,brd_board,til_tile,key_key,rul_rule,dev_device,med_media,evt_event. - Readers ignore unknown fields and show unknown enum values generically, so the API can grow without breaking you.
- Every response carries
X-Request-Id; quote it when you contact support. - Lists return
{ "data": [...], "next_cursor": "..." | null }; passcursorfor the next page.
Endpoint index#
| Method | Path | Auth | Section |
|---|---|---|---|
POST | /auth/register | none (public) | Authentication |
POST | /auth/apple | none (public) | Authentication |
POST | /auth/recover | none (public) | Authentication |
POST | /auth/pairing | session | Authentication |
POST | /auth/pair | none (public) | Authentication |
POST | /auth/logout | session | Authentication |
GET | /me | any token | Authentication |
PATCH | /me | session | Authentication |
DELETE | /me | session | Authentication |
GET | /me/export | session | Authentication |
POST | /cards | write | Cards |
GET | /cards | write (own project) / session (all) | Cards |
GET | /cards/{id} | write (own project) / session | Cards |
GET | /cards/{id}/wait?timeout=50 | write (own project) | Cards |
PATCH | /cards/{id} | write (own project) | Cards |
DELETE | /cards/{id} | write (own project) / session | Cards |
POST | /cards/{id}/respond | session / delegate | Cards |
POST | /cards/{id}/viewed | session | Cards |
GET | /cards/{id}/events | write (own project) / session | Cards |
PUT | /metrics/{name} | write | Metrics |
GET | /metrics | write / session | Metrics |
DELETE | /metrics/{name} | board / session | Metrics |
GET | /boards | write / session | Boards |
POST | /boards | board / session | Boards |
PUT | /boards/{id} | board / session | Boards |
PATCH | /boards/{id}/tiles/{tile_id} | board / session | Boards |
POST | /boards/{id}/tiles | board / session | Boards |
DELETE | /boards/{id}/tiles/{tile_id} | board / session | Boards |
DELETE | /boards/{id} | board / session | Boards |
PUT | /media/{filename} | write | Media |
GET/POST | /projects | admin / session | Projects, keys, rules, webhooks, devices |
PATCH/DELETE | /projects/{id} | admin / session | Projects, keys, rules, webhooks, devices |
GET | /projects/{id}/keys | admin / session | Projects, keys, rules, webhooks, devices |
POST | /projects/{id}/keys | admin / session | Projects, keys, rules, webhooks, devices |
DELETE | /keys/{id} | admin / session | Projects, keys, rules, webhooks, devices |
GET/POST | /rules | admin / session | Projects, keys, rules, webhooks, devices |
PATCH/DELETE | /rules/{id} | admin / session | Projects, keys, rules, webhooks, devices |
POST | /projects/{id}/webhook/test | admin / session | Projects, keys, rules, webhooks, devices |
POST | /devices | session | Projects, keys, rules, webhooks, devices |
GET | /devices | session | Projects, keys, rules, webhooks, devices |
DELETE | /devices/{id} | session | Projects, keys, rules, webhooks, devices |
GET | /stream | session | Realtime |
POST | /billing/apple/transactions | session | Billing (App Store) |
POST | /billing/apple/notifications | Apple | Billing (App Store) |
Authentication#
Two kinds of bearer token in Authorization: Bearer <token>:
| Token | Prefix | Who holds it | Gets |
|---|---|---|---|
| Session | afs_ | the owner's apps (iPhone, iPad, Mac, web) | everything on the account (admin and responding as user) |
| API key | afk_w_ write · afk_b_ board · afk_d_ delegate · afk_a_ admin | agents, scripts, CI | per scope, below |
| Scope | Can |
|---|---|
| write | create/patch/withdraw its project's cards, wait for answers, write metrics, upload media, read its project's cards and metrics |
| board | write + create/replace/patch/delete boards and tiles |
| delegate | board + POST /cards/{id}/respond for cards whose class matches one of delegate_classes (reason required) |
| admin | everything on the account except billing, through the API (projects, keys, rules, webhooks) |
Keys are stored as SHA-256 hashes; the secret is returned once. A revoked or expired key gets 401 unauthorized. allowed_ips (CIDR) is enforced on CF-Connecting-IP.
Sessions (apps)#
| Call | Body → result | Notes |
|---|---|---|
POST /auth/register | {device: {name, platform}} → Session + recovery_code | Creates an account with no email (privacy first). Shows the 24-char recovery code once; the app offers to save it in iCloud Keychain |
POST /auth/apple | {identity_token, authorization_code?, device} → Session | Sign in with Apple; links to an existing account when the Apple user is known, else creates one |
POST /auth/recover | {recovery_code, device} → Session | Restores the account on a new device |
POST /auth/pairing (session) | {} → {code: "483 920", expires_at, qr: "agentsframe://pair?c=…"} | 6 digits, 10 minutes, single use |
POST /auth/pair | {code, device} → Session | Adds a device with a code shown on a signed-in one |
POST /auth/logout (session) | {} → 204 | Revokes this device's session |
GET /me (any) | → Account | For a key: the account plus {key: ApiKey} |
PATCH /me (session) | {name?, interrupt_budget?, quiet_hours?} → Account | |
DELETE /me (session) | {confirm: "DELETE"} → 204 | Deletes the account and all data (App Store 5.1.1) |
GET /me/export (session) | → JSON archive | Every card, event, metric, board, rule |
Cards#
| Call | Scope | Notes |
|---|---|---|
POST /cards | write | Body CardInput → 201 Card. Header Idempotency-Key (≤ 64 chars) replays the first result for 24 h. dedupe_key updates the open card with that key instead of creating one (200) |
GET /cards | write (own project) / session (all) | Query: type, state (comma lists), class (glob), tag, project_id, thread, q (title/body search), limit (≤ 100, default 50), cursor. Newest first. → Page<Card> |
GET /cards/{id} | write (own project) / session | → Card |
GET /cards/{id}/wait?timeout=50 | write (own project) | Long poll. Returns 200 Card as soon as state leaves open; after timeout seconds (1..55) returns 202 with the open Card. Loop until 200 |
PATCH /cards/{id} | write (own project) | CardPatch → Card. Typical: status progress updates. state: "done" / "withdrawn" closes it |
DELETE /cards/{id} | write (own project) / session | Withdraws (poster) or archives (owner) → 204 |
POST /cards/{id}/respond | session / delegate | RespondInput → Card. Validates: card is open; action is one of the card's actions (or submit for question, cancel for a cancellable status, seen for note/preview without actions); required fields and input: required comments present. 409 conflict if already answered |
POST /cards/{id}/viewed | session | Marks viewed (first time only) → 204 |
GET /cards/{id}/events | write (own project) / session | → CardEvent[], oldest first |
Defaults the server applies: approval without actions gets [{id:"approve",label:"Approve",style:"primary"},{id:"deny",label:"Deny",style:"destructive",input:"optional"}]; question gets one submit action implicitly; priority normal; on_expire none.
Validation limits are the comments in types.ts; a violation is 400 bad_request with field.
Expiry: a scheduled sweep (Durable Object alarm) moves open cards past expires_at to expired, applying on_expire as a rule actor response when it names an action.
Metrics#
| Call | Scope | Notes |
|---|---|---|
PUT /metrics/{name} | write | MetricInput → Metric (latest, no points). Points are kept per plan history; at most one point per minute is stored (later writes in the same minute replace it) |
GET /metrics | write / session | → Metric[] (latest values) |
GET /metrics/{name}?range=24h|7d|30d|1y | write / session | → Metric with points (downsampled to ≤ 200) |
DELETE /metrics/{name} | board / session | → 204 |
Boards#
| Call | Scope | Notes |
|---|---|---|
GET /boards | write / session | → Board[] ordered by position |
POST /boards | board / session | BoardInput → 201 Board |
PUT /boards/{id} | board / session | Replaces name/icon/tiles. Tiles with pinned_by_user: true that exist on the server are kept as they are (merged by id) when the writer is a key |
PATCH /boards/{id}/tiles/{tile_id} | board / session | Partial Tile → Board. A session write sets pinned_by_user: true unless the body says otherwise |
POST /boards/{id}/tiles | board / session | Tile without id → Board (appended) |
DELETE /boards/{id}/tiles/{tile_id} · DELETE /boards/{id} | board / session | → 204 |
A new account gets one board "Home" with: open approvals (medium), questions (medium), latest previews (large), running status (medium). An account with no boards gets that default back on GET /boards.
Media#
PUT /media/{filename} (write) with the raw bytes and Content-Type → Media with a url on https://cdn.agentsframe.com/m/{account}/{med_id}/{filename}?sig=… (signed, 7 days, refreshed on every card read). Max 100 MB per file; plan quota media_bytes. Images get width/height; the server never transcodes in v1 (the apps play MP4/HLS/MP3/M4A/WAV natively).
Projects, keys, rules, webhooks, devices#
| Call | Scope | Notes |
|---|---|---|
GET/POST /projects, PATCH/DELETE /projects/{id} | admin / session | {name, tint?, webhook_url?}. A new account has project "Default" |
GET /projects/{id}/keys · POST /projects/{id}/keys | admin / session | POST {name, scope, delegate_classes?, allowed_ips?, expires_at?} → CreatedKey (secret once) |
DELETE /keys/{id} | admin / session | Revoke → 204 |
GET/POST /rules, PATCH/DELETE /rules/{id} | admin / session | Rule; first matching enabled rule (by created order) wins |
POST /projects/{id}/webhook/test | admin / session | Sends a ping |
POST /devices | session | {push_token, push_env} for this session's device → Device |
GET /devices · DELETE /devices/{id} | session | Signing a device out revokes its session |
Webhook delivery (when the project has webhook_url): POST JSON {type: "card.answered"|"card.expired"|"ping", card?, at} with header Frame-Signature: t=<unix>,v1=<hex hmac_sha256(webhook_secret, t + "." + raw_body)>. The secret is shown when the URL is set (webhook_secret in the project response, once). Retries: 1 min, 5 min, 30 min, 2 h, then dropped (recorded as an event).
Notifications policy (server side)#
For each new card the server decides ring (sound + time-sensitive), quiet (delivered, no sound) or none (inbox only):
- A matching rule:
auto_approveanswers at once (actorrule, no notification);silent→ none;interrupt→ ring. notify: "silent"→ none.priority: urgentwith a board/delegate/admin key → ring regardless of budget.- approval and question → ring; preview → quiet; status → none (it updates its Live Activity); note → none.
- Quiet hours (account tz) turn ring into quiet, except urgent.
- Interrupt budget: after
interrupt_budgetrings in 24 h, further rings become quiet.
APNs payloads carry category AF_APPROVAL (actions from the card, up to 4; text input when input ≠ none), AF_QUESTION (Open), AF_PREVIEW (Open, Looks good), AF_NOTE; thread-id = card.thread or project; mutable-content: 1 so the notification service extension fetches the card and attaches the poster image; the alert text is the title only (no body on the lock screen).
Realtime#
GET /stream (session) upgrades to a WebSocket; messages are StreamMessage. The server pings every 30 s; the app reconnects with backoff and refetches GET /cards?state=open after a reconnect.
Billing (App Store)#
| Call | Scope | Notes |
|---|---|---|
POST /billing/apple/transactions | session | {signed_transaction} (StoreKit 2 JWS) → Account with the new plan. The server verifies the JWS chain against Apple's root CA, the bundle id and product id |
POST /billing/apple/notifications | Apple | App Store Server Notifications V2 (signed payload): renew, expire, refund, grace period, revoke |
Products: com.agentsframe.pro.monthly (7.99 USD), com.agentsframe.pro.yearly (59.99 USD, 7-day free trial). Subscription group Agents Frame Pro.
| Limit | free | pro |
|---|---|---|
| projects | 1 | 50 |
| boards | 1 | 50 |
| keys | 1 | 100 |
| cards_per_month | 200 | 20000 |
| media_bytes | 500 MB | 20 GB |
| history_days | 30 | 365 |
| rules / webhooks / delegate keys | no | yes |
Over the card quota: 402 quota_exceeded with hint (no silent drop). A feature outside the plan: 402 plan_required.
Rate limits and errors#
Per key: 20 requests/s burst, 600/min sustained; per session 50/s. Over: 429 rate_limited with Retry-After. Errors always use ErrorBody. Every response carries X-Request-Id.
Versioning#
/v1 is additive only. A field is never repurposed; removals wait for /v2. Clients send User-Agent: agentsframe-<client>/<version>.
Server behaviour that completes this contract#
Decisions the sections above leave open. They are additive and binding for clients.
GET /healthandGET /v1/healthreturn{ok, version, environment, at};GET /returns service info. No authentication.- Keys below
delegate(write, board) only see and change cards of their own project. Delegate and admin keys read cards of every project (a supervisor must see what it answers). Metrics and boards belong to the account, not a project. - A key cannot answer a card with
require_unlock: true(403): the owner must unlock. A delegate key answers only classes matchingdelegate_classes; an admin key may answer with areason. The reason is stored inCardResponse.reason. Idempotency-Keyis scoped to the key's project. Reusing it with a different body is 409conflict. Only successful results are stored.- A dedupe update (
dedupe_key) neither counts againstcards_per_monthnor notifies again. A ruleexpire_defaultsetson_expireto the rule'sactionwhen the card has none. DELETE /cards/{id}by the owner archives: an open card is withdrawn first, then hidden fromGET /cards(still readable by id). Closed cards older than the plan'shistory_daysleaveGET /cards; open cards never do.- A key
PATCH/DELETEon a tile withpinned_by_user: truesucceeds without changing it (the same rule asPUT). POST /projects/{id}/webhook/testreturns 202{queued: true}. A webhook that gave up is recorded on the card as eventdeliveredwithdata: {channel: "webhook", status: "dropped"}.webhook_secretappears once in the response that first setswebhook_url; settingwebhook_urltonulland again rotates it.PUT /media/{filename}needsContent-Length; filenames are 1..200 characters of letters, digits and. _ - ( ) +and space, not starting with a dot. The response is 201. Signed URLs carryexp(unix seconds) andsigand expire after 7 days; they are re-signed whenever a card is read.- Unauthenticated endpoints (
register,recover,pair,apple) are throttled per IP (429rate_limitedwithRetry-After). - A plan that lapsed without a notification falls back to free two days after
plan_renews_at.
Error codes#
Requests that fail return a non-2xx status and an ErrorBody. Codes and statuses:
error.code | HTTP | Meaning |
|---|---|---|
bad_request | 400 | The body or a query parameter is invalid. error.field names the offending field. |
unauthorized | 401 | Missing, malformed, revoked or expired token, or the request came from an IP outside the key's allowed_ips. |
forbidden | 403 | The token is valid but its scope or plan does not allow this call. |
not_found | 404 | The resource does not exist or belongs to another project. |
conflict | 409 | The state forbids the change, for example answering a card that was already answered. |
gone | 410 | The resource existed but is permanently gone (an expired pairing code, a deleted account). |
payload_too_large | 413 | A body or a media file is over the limit (100 MB per file). |
rate_limited | 429 | Too many requests. Wait Retry-After seconds. |
quota_exceeded | 402 | The plan's monthly card or media quota is used up. hint says how to continue; nothing is dropped silently. |
plan_required | 402 | The feature (rules, webhooks, delegate keys, more projects) needs Pro. |
internal | 500 | Something failed on our side. Safe to retry with the same Idempotency-Key. |
Webhooks#
When a project has a webhook_url, Frame sends a POST with a JSON body for each event:
{ "type": "card.answered", "card": { "id": "crd_8f2k1x", "state": "answered", "response": { "action": "approve" } }, "at": "2026-11-16T18:00:09.000Z" }type is card.answered, card.expired or ping (sent by POST /projects/{id}/webhook/test). Each request has the header
Frame-Signature: t=1763316009,v1=5b1c0f…where v1 is the hex HMAC-SHA256 of t + "." + raw_body with the project's webhook_secret. The secret is returned once when you set the URL. To verify a delivery, use the raw request body (not a re-serialised object), recompute the HMAC, compare in constant time and reject timestamps older than five minutes to stop replays.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyFrameSignature(secret: string, header: string, rawBody: string, toleranceSeconds = 300): boolean {
const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=") as [string, string]));
const t = Number(parts.t);
if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const given = parts.v1 ?? "";
return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
// Express: app.post("/frame", express.raw({ type: "application/json" }), (req, res) => {
// if (!verifyFrameSignature(SECRET, req.header("Frame-Signature") ?? "", req.body.toString("utf8"))) return res.sendStatus(401);
// const event = JSON.parse(req.body.toString("utf8")); ...; res.sendStatus(200);
// });import hashlib, hmac, time
def verify_frame_signature(secret: str, header: str, raw_body: bytes, tolerance: int = 300) -> bool:
parts = dict(p.strip().split("=", 1) for p in header.split(","))
try:
t = int(parts["t"])
except (KeyError, ValueError):
return False
if abs(time.time() - t) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(parts.get("v1", ""), expected)
# FastAPI:
# @app.post("/frame")
# async def frame(request: Request):
# body = await request.body()
# if not verify_frame_signature(SECRET, request.headers.get("frame-signature", ""), body):
# raise HTTPException(401)Respond with any 2xx within 10 seconds. Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes and 2 hours, then dropped and recorded as an event on the card. Deliveries can repeat, so make your handler idempotent (use the card id). Use frame webhook verify to debug a signature locally.
Examples#
Valid instances from contract/fixtures, the same files the server and apps test against.
Create a card (response)#
An approval card as returned by POST /cards and GET /cards/{id}.
{
"id": "crd_demo01",
"type": "approval",
"title": "Deploy v2.3.1 to production?",
"priority": "high",
"state": "open",
"source": {
"agent": "release-bot",
"host": "ci-2",
"url": "https://github.com/acme/api/pull/412",
"key_name": "CI",
"project_id": "prj_demo"
},
"created_at": "2026-11-16T18:00:00.000Z",
"updated_at": "2026-11-16T18:00:00.000Z",
"url": "https://app.agentsframe.com/c/crd_demo01",
"body": "3 files changed · 212 tests passed · staging healthy for 2 h.\n\n```diff\n- timeout: 30\n+ timeout: 45\n```",
"class": "deploy.production",
"actions": [
{
"id": "approve",
"label": "Deploy",
"style": "primary"
},
{
"id": "deny",
"label": "Hold",
"style": "destructive",
"input": "optional",
"input_placeholder": "Why hold?"
}
],
"require_unlock": true,
"expires_at": "2026-11-16T19:00:00.000Z",
"on_expire": "deny",
"tags": [
"api",
"release"
]
}Approval with a comment field#
The body of a POST /cards request: an approval whose action asks for a comment.
{
"type": "approval",
"title": "Deploy v2.3.1 to production?",
"class": "deploy.production",
"priority": "high",
"ttl": 3600,
"on_expire": "deny",
"actions": [
{
"id": "approve",
"label": "Deploy",
"style": "primary"
},
{
"id": "deny",
"label": "Hold",
"style": "destructive",
"input": "optional"
}
],
"source": {
"agent": "release-bot",
"host": "ci-2"
}
}Question#
A question card with typed fields.
{
"id": "crd_demo02",
"type": "question",
"title": "Which thumbnail should go live?",
"priority": "normal",
"state": "open",
"source": {
"agent": "video-agent",
"host": "studio-mac",
"key_name": "Studio",
"project_id": "prj_demo"
},
"created_at": "2026-11-16T18:00:00.000Z",
"updated_at": "2026-11-16T18:00:00.000Z",
"url": "https://app.agentsframe.com/c/crd_demo02",
"body": "Three options rendered for the Tuesday video.",
"class": "content.thumbnail",
"fields": [
{
"id": "pick",
"kind": "choice",
"label": "Thumbnail",
"options": [
{
"id": "a",
"label": "A · Bold title"
},
{
"id": "b",
"label": "B · Face close-up"
},
{
"id": "c",
"label": "C · Before/after"
}
],
"required": true
},
{
"id": "note",
"kind": "textarea",
"label": "Notes for the editor",
"placeholder": "Optional"
}
],
"media": [
{
"kind": "image",
"url": "https://picsum.photos/id/1015/1280/720",
"name": "a.jpg",
"width": 1280,
"height": 720
},
{
"kind": "image",
"url": "https://picsum.photos/id/1025/1280/720",
"name": "b.jpg",
"width": 1280,
"height": 720
},
{
"kind": "image",
"url": "https://picsum.photos/id/1035/1280/720",
"name": "c.jpg",
"width": 1280,
"height": 720
}
]
}Preview: video#
A preview card for a video with review actions.
{
"id": "crd_demo03",
"type": "preview",
"title": "Episode 12 · final cut (18:02)",
"priority": "normal",
"state": "open",
"source": {
"agent": "render-farm",
"host": "gpu-1",
"key_name": "Render",
"project_id": "prj_demo"
},
"created_at": "2026-11-16T18:00:00.000Z",
"updated_at": "2026-11-16T18:00:00.000Z",
"url": "https://app.agentsframe.com/c/crd_demo03",
"body": "Rendered at 1080p60. Chapters and captions burned in.",
"class": "video.final",
"preview": {
"kind": "video",
"url": "https://devstreaming-cdn.apple.com/videos/streaming/examples/img_bipbop_adv_example_fmp4/master.m3u8",
"poster": "https://picsum.photos/id/1043/1280/720",
"duration": 1082,
"title": "Episode 12"
},
"actions": [
{
"id": "looks_good",
"label": "Looks good",
"style": "primary"
},
{
"id": "changes",
"label": "Request changes",
"input": "required",
"input_placeholder": "What should change?"
}
]
}Preview: Markdown#
A preview card that renders Markdown from a URL.
{
"id": "crd_demo04",
"type": "preview",
"title": "Weekly research report",
"priority": "normal",
"state": "open",
"source": {
"agent": "research-agent",
"host": "cloud",
"key_name": "Research",
"project_id": "prj_demo"
},
"created_at": "2026-11-16T18:00:00.000Z",
"updated_at": "2026-11-16T18:00:00.000Z",
"url": "https://app.agentsframe.com/c/crd_demo04",
"body": "12 sources, 4 findings, 2 open questions.",
"class": "research.weekly",
"preview": {
"kind": "markdown",
"url": "https://raw.githubusercontent.com/github/docs/main/README.md",
"title": "Report"
}
}Preview: folder#
A preview card that lists a folder the owner can browse.
{
"id": "crd_demo05",
"type": "preview",
"title": "Brand kit export",
"priority": "normal",
"state": "open",
"source": {
"agent": "design-agent",
"host": "mac-studio",
"key_name": "Design",
"project_id": "prj_demo"
},
"created_at": "2026-11-16T18:00:00.000Z",
"updated_at": "2026-11-16T18:00:00.000Z",
"url": "https://app.agentsframe.com/c/crd_demo05",
"class": "design.export",
"preview": {
"kind": "folder",
"title": "brand-kit/",
"items": [
{
"name": "logo.png",
"kind": "image",
"url": "https://picsum.photos/id/1062/800/800",
"size": 182044
},
{
"name": "guidelines.pdf",
"kind": "pdf",
"url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
"size": 13264
},
{
"name": "jingle.mp3",
"kind": "audio",
"url": "https://download.samplelib.com/mp3/sample-6s.mp3",
"size": 95000
},
{
"name": "social",
"kind": "folder",
"items": [
{
"name": "banner.jpg",
"kind": "image",
"url": "https://picsum.photos/id/1067/1500/500"
}
]
}
]
}
}Status with progress#
A status card as updated with PATCH /cards/{id}.
{
"id": "crd_demo06",
"type": "status",
"title": "Nightly data import",
"priority": "normal",
"state": "open",
"source": {
"agent": "etl",
"host": "worker-3",
"key_name": "ETL",
"project_id": "prj_demo"
},
"created_at": "2026-11-16T18:00:00.000Z",
"updated_at": "2026-11-16T18:00:00.000Z",
"url": "https://app.agentsframe.com/c/crd_demo06",
"class": "etl.nightly",
"progress": {
"state": "running",
"value": 0.62,
"label": "Importing 6 of 10 tables",
"steps": [
{
"label": "Extract",
"state": "done"
},
{
"label": "Transform",
"state": "done"
},
{
"label": "Load",
"state": "active"
},
{
"label": "Verify",
"state": "pending"
}
]
},
"cancellable": true
}Metric#
A Metric as returned by PUT /metrics/{name} and GET /metrics.
{
"name": "youtube.subscribers",
"label": "Subscribers",
"unit": "subs",
"format": "compact",
"value": 48210,
"previous": 47980,
"better": "up",
"goal": 50000,
"updated_at": "2026-11-16T18:00:00.000Z",
"points": [
{
"at": "2026-11-10T18:00:00.000Z",
"value": 46900
},
{
"at": "2026-11-11T18:00:00.000Z",
"value": 47120
},
{
"at": "2026-11-12T18:00:00.000Z",
"value": 47300
},
{
"at": "2026-11-13T18:00:00.000Z",
"value": 47510
},
{
"at": "2026-11-14T18:00:00.000Z",
"value": 47760
},
{
"at": "2026-11-15T18:00:00.000Z",
"value": 47980
},
{
"at": "2026-11-16T18:00:00.000Z",
"value": 48210
}
]
}Board#
A Board as returned by GET /boards (the default Home board).
{
"id": "brd_home",
"name": "Home",
"icon": "square.grid.2x2",
"position": 0,
"updated_at": "2026-11-16T18:00:00.000Z",
"updated_by": {
"kind": "system",
"name": "default"
},
"tiles": [
{
"id": "til_approvals",
"title": "Needs you",
"size": "medium",
"tint": "indigo",
"icon": "checkmark.seal",
"source": {
"kind": "cards",
"filter": {
"type": [
"approval",
"question"
],
"state": [
"open"
],
"limit": 10
}
}
},
{
"id": "til_subs",
"size": "small",
"tint": "red",
"icon": "play.rectangle",
"source": {
"kind": "metric",
"metric": "youtube.subscribers"
}
},
{
"id": "til_mrr",
"size": "small",
"tint": "green",
"icon": "dollarsign.circle",
"source": {
"kind": "metric",
"metric": "revenue.mrr"
}
},
{
"id": "til_results",
"title": "Latest results",
"size": "large",
"tint": "purple",
"icon": "sparkles.rectangle.stack",
"source": {
"kind": "cards",
"filter": {
"type": [
"preview"
],
"state": [
"open",
"answered",
"done"
],
"limit": 6
}
}
},
{
"id": "til_running",
"title": "Running",
"size": "medium",
"tint": "blue",
"icon": "gauge.with.dots.needle.67percent",
"source": {
"kind": "cards",
"filter": {
"type": [
"status"
],
"state": [
"open"
],
"limit": 5
}
}
},
{
"id": "til_ops",
"size": "medium",
"tint": "teal",
"icon": "chart.bar",
"source": {
"kind": "metrics",
"metrics": [
"api.p95",
"agents.running"
]
}
},
{
"id": "til_note",
"title": "Today",
"size": "medium",
"tint": "yellow",
"icon": "note.text",
"source": {
"kind": "text",
"markdown": "**Focus:** ship v2.3 · review Episode 12 · approve GPU budget"
}
}
]
}Created key#
The response of POST /projects/{id}/keys. The secret is shown once.
{
"id": "key_demo",
"project_id": "prj_demo",
"name": "CI",
"scope": "write",
"prefix": "afk_w_3fa9",
"created_at": "2026-11-16T18:00:00.000Z",
"secret": "afk_w_3fa9c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8"
}Types#
The shapes below are taken verbatim from contract/types.ts. Comments are the validation rules.
Shared#
ISODate#
export type ISODate = string;Tint#
export type Tint = "indigo" | "blue" | "teal" | "green" | "yellow" | "orange" | "red" | "pink" | "purple" | "gray";Priority#
export type Priority = "low" | "normal" | "high" | "urgent";Page#
export interface Page<T> {
data: T[];
next_cursor: string | null;
}ErrorBody#
Every non-2xx response. code is stable and machine-readable; hint says what to do.
export interface ErrorBody {
error: {
code:
| "bad_request" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "gone"
| "payload_too_large" | "rate_limited" | "quota_exceeded" | "plan_required" | "internal";
message: string;
hint?: string;
field?: string; // the offending request field, dotted path ("fields.2.options")
};
}Actor#
Who did something. kind user = the owner on a signed-in device; key = an API key; rule = an automatic rule.
export interface Actor {
kind: "user" | "key" | "rule" | "system";
name: string; // device name, key name, rule name
id?: string; // dev_ / key_ / rul_ id
}Source#
export interface Source {
agent?: string; // free text: "release-bot", "claude-code"
host?: string; // "ci-2", "mini"
url?: string; // where the agent lives (a run, a PR)
key_name?: string; // set by the server from the API key that posted (cannot be spoofed)
project_id?: string; // set by the server
}Link#
export interface Link {
label: string;
url: string;
}Media and previews#
MediaKind#
export type MediaKind =
| "image" | "video" | "audio" | "pdf" | "markdown" | "web" | "document" | "model3d" | "file";Media#
export interface Media {
kind: MediaKind;
url: string; // https URL (our R2 via /v1/media, or any public/third-party URL)
name?: string;
mime?: string;
size?: number; // bytes
width?: number;
height?: number;
duration?: number; // seconds (audio/video)
poster?: string; // image URL shown before play / as thumbnail
}Preview#
A rendered result to look at. folder lists entries the user can open one by one.
export interface Preview {
kind: MediaKind | "gallery" | "folder";
url?: string; // single item kinds
poster?: string;
duration?: number;
title?: string;
items?: FolderItem[]; // gallery and folder
}FolderItem#
export interface FolderItem {
name: string;
kind: MediaKind | "folder";
url?: string; // absent for a sub-folder listed only by name
size?: number;
modified?: ISODate;
poster?: string;
items?: FolderItem[]; // nested folder (max depth 4, max 500 items total)
}Cards#
CardType#
export type CardType = "approval" | "question" | "preview" | "status" | "note";CardState#
export type CardState = "open" | "answered" | "expired" | "withdrawn" | "done";Action#
export interface Action {
id: string; // [a-z0-9_-]{1,32}; returned in the response
label: string; // <= 24 chars
style?: "primary" | "default" | "destructive";
input?: "none" | "optional" | "required"; // a short comment typed with the tap (notification text input too)
input_placeholder?: string;
}FieldKind#
export type FieldKind = "text" | "textarea" | "choice" | "multichoice" | "number" | "date" | "toggle";Field#
export interface Field {
id: string; // [a-z0-9_-]{1,32}
kind: FieldKind;
label: string;
placeholder?: string;
options?: { id: string; label: string }[]; // choice / multichoice, 2..12
required?: boolean;
default?: string | number | boolean | string[];
min?: number; // number
max?: number;
}Progress#
export interface Progress {
state: "running" | "succeeded" | "failed" | "cancelled";
value?: number; // 0..1, absent = indeterminate
label?: string; // "Rendering 3/8"
steps?: { label: string; state: "pending" | "active" | "done" | "failed" | "skipped" }[];
eta?: ISODate;
}CardResponse#
export interface CardResponse {
action: string; // Action.id (approval / preview review) or "submit" (question) or "cancel" (status)
values?: Record<string, string | number | boolean | string[]>; // question fields by id
comment?: string;
reason?: string; // set when a delegate key answered: why (shown on the card)
by: Actor;
at: ISODate;
}Card#
export interface Card {
id: string; // crd_
type: CardType;
title: string; // 1..120
body?: string; // markdown, <= 20000
class?: string; // dotted, for rules: "deploy.production"
priority: Priority; // default normal
state: CardState;
source: Source;
tags?: string[]; // <= 10, each <= 32
links?: Link[]; // <= 5
media?: Media[]; // attachments shown under the body, <= 20
thread?: string; // group key: cards with the same thread stack together
// type specific
actions?: Action[]; // approval (default approve/deny), preview review (optional), <= 4
fields?: Field[]; // question, 1..12
preview?: Preview; // preview
progress?: Progress; // status
cancellable?: boolean; // status: shows a Cancel action
require_unlock?: boolean; // approval: answering needs Face ID / Touch ID / password
// lifecycle
response?: CardResponse;
expires_at?: ISODate;
on_expire?: "none" | string; // "none" or an Action.id applied automatically at expiry
created_at: ISODate;
updated_at: ISODate;
answered_at?: ISODate;
viewed_at?: ISODate;
url: string; // https://app.agentsframe.com/c/{id}
metadata?: Record<string, unknown>; // opaque to Frame, returned as is (<= 4 KB)
}CardInput#
POST /v1/cards body. Server fills id, state, source.key_name/project_id, timestamps, url.
export interface CardInput {
type: CardType;
title: string;
body?: string;
class?: string;
priority?: Priority;
source?: Omit<Source, "key_name" | "project_id">;
tags?: string[];
links?: Link[];
media?: Media[];
thread?: string;
actions?: Action[];
fields?: Field[];
preview?: Preview;
progress?: Progress;
cancellable?: boolean;
require_unlock?: boolean;
ttl?: number; // seconds, 60..2592000; sets expires_at
on_expire?: "none" | string;
dedupe_key?: string; // an open card with the same key in the project is updated instead of duplicated
metadata?: Record<string, unknown>;
notify?: "auto" | "silent" | "interrupt"; // hint; rules and the interrupt budget decide (urgent needs a board+ key)
}CardPatch#
PATCH /v1/cards/{id}: any subset; typically progress for status cards, or body/preview.
export type CardPatch = Partial<Pick<CardInput, "title" | "body" | "priority" | "tags" | "links" | "media" | "preview" | "progress" | "metadata">> & {
state?: "done" | "withdrawn"; // the poster closes its own card
};RespondInput#
POST /v1/cards/{id}/respond (owner session or a delegate key).
export interface RespondInput {
action: string;
values?: Record<string, string | number | boolean | string[]>;
comment?: string;
reason?: string; // required for a delegate key; shown on the card
}CardEvent#
export interface CardEvent {
id: string; // evt_
card_id: string;
kind: "created" | "updated" | "delivered" | "viewed" | "answered" | "delegated" | "expired" | "withdrawn" | "done";
actor: Actor;
at: ISODate;
data?: Record<string, unknown>; // e.g. { action, device } for answered; { fields: [...] } for updated
}Metrics#
MetricPoint#
export interface MetricPoint {
at: ISODate;
value: number;
}Metric#
export interface Metric {
name: string; // [a-z0-9][a-z0-9._-]{0,63} e.g. "youtube.subscribers"
label: string;
unit?: string; // "subs", "$", "ms"
format: "number" | "compact" | "percent" | "currency" | "duration";
currency?: string; // ISO 4217 when format = currency
value: number; // latest
previous?: number; // value 24 h before latest (server computed)
better: "up" | "down" | "none"; // colours the delta
goal?: number;
updated_at: ISODate;
points?: MetricPoint[]; // GET /v1/metrics/{name}?range=24h|7d|30d|1y
}MetricInput#
PUT /v1/metrics/{name}: write one point; descriptive fields are upserted when present.
export interface MetricInput {
value: number;
at?: ISODate;
label?: string;
unit?: string;
format?: Metric["format"];
currency?: string;
better?: Metric["better"];
goal?: number;
}Boards (the dynamic shell)#
TileSize#
export type TileSize = "small" | "medium" | "large"; // 1x1, 2x1, 2x2 grid cellsTileSource#
What a tile shows. Exactly one shape per kind.
export type TileSource =
| { kind: "metric"; metric: string } // number + delta + sparkline
| { kind: "metrics"; metrics: string[] } // up to 4 small numbers
| { kind: "cards"; filter: CardFilter } // a live stack/list of cards
| { kind: "card"; card_id: string } // one pinned card
| { kind: "text"; markdown: string } // a note written by the agent
| { kind: "link"; url: string; label: string; icon?: string }; // a shortcutCardFilter#
export interface CardFilter {
type?: CardType[];
state?: CardState[]; // default ["open"]
class?: string; // glob: "deploy.*"
tag?: string;
project_id?: string;
thread?: string;
limit?: number; // 1..50, default 20
}Tile#
export interface Tile {
id: string; // til_ (client may propose; server keeps it)
title?: string;
size: TileSize;
tint?: Tint;
icon?: string; // SF Symbol name; validated against an allowlist pattern [a-z0-9.]+
source: TileSource;
pinned_by_user?: boolean; // the owner moved/resized it: API writes leave it alone
}Board#
export interface Board {
id: string; // brd_
name: string; // 1..40
icon?: string; // SF Symbol
position: number; // order among boards
tiles: Tile[]; // flow layout in order; <= 60
updated_at: ISODate;
updated_by: Actor;
}BoardInput#
PUT /v1/boards/{id} or POST /v1/boards.
export interface BoardInput {
name: string;
icon?: string;
position?: number;
tiles: Omit<Tile, "id">[] | Tile[];
}Accounts, projects, keys, rules#
Plan#
export type Plan = "free" | "pro";Limits#
export interface Limits {
projects: number;
boards: number;
keys: number;
cards_per_month: number;
media_bytes: number;
history_days: number;
rules: boolean;
webhooks: boolean;
delegate_keys: boolean;
}Account#
export interface Account {
id: string; // acc_
name: string; // display name
email?: string;
plan: Plan;
plan_renews_at?: ISODate;
plan_source?: "app_store" | "grant";
limits: Limits;
usage: { cards_this_month: number; media_bytes: number };
interrupt_budget: number; // rings per day, default 5
quiet_hours?: { start: string; end: string; tz: string }; // "23:00", "07:00", IANA tz
created_at: ISODate;
}Project#
export interface Project {
id: string; // prj_
name: string;
tint?: Tint;
webhook_url?: string;
webhook_secret?: string; // returned once, in the response that sets webhook_url
created_at: ISODate;
}KeyScope#
export type KeyScope = "write" | "board" | "delegate" | "admin";ApiKey#
export interface ApiKey {
id: string; // key_
project_id: string;
name: string;
scope: KeyScope; // write < board < delegate (delegate = write + respond for allowed classes); admin = everything
prefix: string; // "afk_w_3fa9" — first 10 chars, for display
delegate_classes?: string[]; // globs a delegate key may answer
allowed_ips?: string[]; // CIDR
expires_at?: ISODate;
last_used_at?: ISODate;
created_at: ISODate;
revoked_at?: ISODate;
}CreatedKey#
Returned once by POST /v1/projects/{id}/keys; secret is never shown again.
export interface CreatedKey extends ApiKey {
secret: string; // "afk_w_…" 40+ chars
}Rule#
export interface Rule {
id: string; // rul_
name: string;
class: string; // glob over Card.class
effect: "auto_approve" | "silent" | "interrupt" | "expire_default";
action?: string; // auto_approve: which Action.id (default "approve")
enabled: boolean;
created_at: ISODate;
}Sessions, devices, realtime, billing#
Session#
export interface Session {
token: string; // "afs_…" bearer for the apps
account: Account;
device: Device;
}Device#
export interface Device {
id: string; // dev_
name: string; // "Leo's iPhone"
platform: "ios" | "ipados" | "macos" | "web";
push_token?: string; // APNs hex token (absent until granted)
push_env?: "sandbox" | "production";
last_seen_at?: ISODate;
created_at: ISODate;
}StreamMessage#
Messages on GET /v1/stream (WebSocket, session token as ?token= or Authorization).
export type StreamMessage =
| { type: "hello"; account_id: string; at: ISODate }
| { type: "card"; card: Card } // created or changed
| { type: "card_removed"; card_id: string }
| { type: "board"; board: Board }
| { type: "board_removed"; board_id: string }
| { type: "metric"; metric: Metric } // latest value changed (no points)
| { type: "account"; account: Account }
| { type: "ping"; at: ISODate };