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.

your first request
curl https://api.agentsframe.com/v1/me -H "Authorization: Bearer $AGENTSFRAME_KEY"

Conventions#

  • JSON, UTF-8, snake_case keys, 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 }; pass cursor for the next page.

Endpoint index#

MethodPathAuthSection
POST/auth/registernone (public)Authentication
POST/auth/applenone (public)Authentication
POST/auth/recovernone (public)Authentication
POST/auth/pairingsessionAuthentication
POST/auth/pairnone (public)Authentication
POST/auth/logoutsessionAuthentication
GET/meany tokenAuthentication
PATCH/mesessionAuthentication
DELETE/mesessionAuthentication
GET/me/exportsessionAuthentication
POST/cardswriteCards
GET/cardswrite (own project) / session (all)Cards
GET/cards/{id}write (own project) / sessionCards
GET/cards/{id}/wait?timeout=50write (own project)Cards
PATCH/cards/{id}write (own project)Cards
DELETE/cards/{id}write (own project) / sessionCards
POST/cards/{id}/respondsession / delegateCards
POST/cards/{id}/viewedsessionCards
GET/cards/{id}/eventswrite (own project) / sessionCards
PUT/metrics/{name}writeMetrics
GET/metricswrite / sessionMetrics
DELETE/metrics/{name}board / sessionMetrics
GET/boardswrite / sessionBoards
POST/boardsboard / sessionBoards
PUT/boards/{id}board / sessionBoards
PATCH/boards/{id}/tiles/{tile_id}board / sessionBoards
POST/boards/{id}/tilesboard / sessionBoards
DELETE/boards/{id}/tiles/{tile_id}board / sessionBoards
DELETE/boards/{id}board / sessionBoards
PUT/media/{filename}writeMedia
GET/POST/projectsadmin / sessionProjects, keys, rules, webhooks, devices
PATCH/DELETE/projects/{id}admin / sessionProjects, keys, rules, webhooks, devices
GET/projects/{id}/keysadmin / sessionProjects, keys, rules, webhooks, devices
POST/projects/{id}/keysadmin / sessionProjects, keys, rules, webhooks, devices
DELETE/keys/{id}admin / sessionProjects, keys, rules, webhooks, devices
GET/POST/rulesadmin / sessionProjects, keys, rules, webhooks, devices
PATCH/DELETE/rules/{id}admin / sessionProjects, keys, rules, webhooks, devices
POST/projects/{id}/webhook/testadmin / sessionProjects, keys, rules, webhooks, devices
POST/devicessessionProjects, keys, rules, webhooks, devices
GET/devicessessionProjects, keys, rules, webhooks, devices
DELETE/devices/{id}sessionProjects, keys, rules, webhooks, devices
GET/streamsessionRealtime
POST/billing/apple/transactionssessionBilling (App Store)
POST/billing/apple/notificationsAppleBilling (App Store)

Authentication#

Two kinds of bearer token in Authorization: Bearer <token>:

TokenPrefixWho holds itGets
Sessionafs_the owner's apps (iPhone, iPad, Mac, web)everything on the account (admin and responding as user)
API keyafk_w_ write · afk_b_ board · afk_d_ delegate · afk_a_ adminagents, scripts, CIper scope, below
ScopeCan
writecreate/patch/withdraw its project's cards, wait for answers, write metrics, upload media, read its project's cards and metrics
boardwrite + create/replace/patch/delete boards and tiles
delegateboard + POST /cards/{id}/respond for cards whose class matches one of delegate_classes (reason required)
admineverything 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)#

CallBody → resultNotes
POST /auth/register{device: {name, platform}} → Session + recovery_codeCreates 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} → SessionSign in with Apple; links to an existing account when the Apple user is known, else creates one
POST /auth/recover{recovery_code, device} → SessionRestores 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} → SessionAdds a device with a code shown on a signed-in one
POST /auth/logout (session){} → 204Revokes this device's session
GET /me (any)→ AccountFor a key: the account plus {key: ApiKey}
PATCH /me (session){name?, interrupt_budget?, quiet_hours?} → Account
DELETE /me (session){confirm: "DELETE"} → 204Deletes the account and all data (App Store 5.1.1)
GET /me/export (session)→ JSON archiveEvery card, event, metric, board, rule

Cards#

CallScopeNotes
POST /cardswriteBody 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 /cardswrite (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=50write (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) / sessionWithdraws (poster) or archives (owner) → 204
POST /cards/{id}/respondsession / delegateRespondInput → 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}/viewedsessionMarks viewed (first time only) → 204
GET /cards/{id}/eventswrite (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#

CallScopeNotes
PUT /metrics/{name}writeMetricInput → 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 /metricswrite / session→ Metric[] (latest values)
GET /metrics/{name}?range=24h|7d|30d|1ywrite / session→ Metric with points (downsampled to ≤ 200)
DELETE /metrics/{name}board / session→ 204

Boards#

CallScopeNotes
GET /boardswrite / session→ Board[] ordered by position
POST /boardsboard / sessionBoardInput → 201 Board
PUT /boards/{id}board / sessionReplaces 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 / sessionPartial Tile → Board. A session write sets pinned_by_user: true unless the body says otherwise
POST /boards/{id}/tilesboard / sessionTile 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#

CallScopeNotes
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}/keysadmin / sessionPOST {name, scope, delegate_classes?, allowed_ips?, expires_at?} → CreatedKey (secret once)
DELETE /keys/{id}admin / sessionRevoke → 204
GET/POST /rules, PATCH/DELETE /rules/{id}admin / sessionRule; first matching enabled rule (by created order) wins
POST /projects/{id}/webhook/testadmin / sessionSends a ping
POST /devicessession{push_token, push_env} for this session's device → Device
GET /devices · DELETE /devices/{id}sessionSigning 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):

  1. A matching rule: auto_approve answers at once (actor rule, no notification); silent → none; interrupt → ring.
  2. notify: "silent" → none. priority: urgent with a board/delegate/admin key → ring regardless of budget.
  3. approval and question → ring; preview → quiet; status → none (it updates its Live Activity); note → none.
  4. Quiet hours (account tz) turn ring into quiet, except urgent.
  5. Interrupt budget: after interrupt_budget rings 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)#

CallScopeNotes
POST /billing/apple/transactionssession{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/notificationsAppleApp 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.

Limitfreepro
projects150
boards150
keys1100
cards_per_month20020000
media_bytes500 MB20 GB
history_days30365
rules / webhooks / delegate keysnoyes

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 /health and GET /v1/health return {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 matching delegate_classes; an admin key may answer with a reason. The reason is stored in CardResponse.reason.
  • Idempotency-Key is scoped to the key's project. Reusing it with a different body is 409 conflict. Only successful results are stored.
  • A dedupe update (dedupe_key) neither counts against cards_per_month nor notifies again. A rule expire_default sets on_expire to the rule's action when the card has none.
  • DELETE /cards/{id} by the owner archives: an open card is withdrawn first, then hidden from GET /cards (still readable by id). Closed cards older than the plan's history_days leave GET /cards; open cards never do.
  • A key PATCH/DELETE on a tile with pinned_by_user: true succeeds without changing it (the same rule as PUT).
  • POST /projects/{id}/webhook/test returns 202 {queued: true}. A webhook that gave up is recorded on the card as event delivered with data: {channel: "webhook", status: "dropped"}. webhook_secret appears once in the response that first sets webhook_url; setting webhook_url to null and again rotates it.
  • PUT /media/{filename} needs Content-Length; filenames are 1..200 characters of letters, digits and . _ - ( ) + and space, not starting with a dot. The response is 201. Signed URLs carry exp (unix seconds) and sig and expire after 7 days; they are re-signed whenever a card is read.
  • Unauthenticated endpoints (register, recover, pair, apple) are throttled per IP (429 rate_limited with Retry-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.codeHTTPMeaning
bad_request400The body or a query parameter is invalid. error.field names the offending field.
unauthorized401Missing, malformed, revoked or expired token, or the request came from an IP outside the key's allowed_ips.
forbidden403The token is valid but its scope or plan does not allow this call.
not_found404The resource does not exist or belongs to another project.
conflict409The state forbids the change, for example answering a card that was already answered.
gone410The resource existed but is permanently gone (an expired pairing code, a deleted account).
payload_too_large413A body or a media file is over the limit (100 MB per file).
rate_limited429Too many requests. Wait Retry-After seconds.
quota_exceeded402The plan's monthly card or media quota is used up. hint says how to continue; nothing is dropped silently.
plan_required402The feature (rules, webhooks, delegate keys, more projects) needs Pro.
internal500Something 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:

body
{ "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

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.

TypeScript (Node, Hono, Express)
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);
// });
Python
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}.

json
{
  "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.

json
{
  "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.

json
{
  "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.

json
{
  "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.

json
{
  "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.

json
{
  "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}.

json
{
  "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.

json
{
  "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).

json
{
  "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.

json
{
  "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#

ts
export type ISODate = string;

Tint#

ts
export type Tint = "indigo" | "blue" | "teal" | "green" | "yellow" | "orange" | "red" | "pink" | "purple" | "gray";

Priority#

ts
export type Priority = "low" | "normal" | "high" | "urgent";

Page#

ts
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.

ts
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.

ts
export interface Actor {
  kind: "user" | "key" | "rule" | "system";
  name: string;          // device name, key name, rule name
  id?: string;           // dev_ / key_ / rul_ id
}

Source#

ts
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
}
ts
export interface Link {
  label: string;
  url: string;
}

Media and previews#

MediaKind#

ts
export type MediaKind =
  | "image" | "video" | "audio" | "pdf" | "markdown" | "web" | "document" | "model3d" | "file";

Media#

ts
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.

ts
export interface Preview {
  kind: MediaKind | "gallery" | "folder";
  url?: string;           // single item kinds
  poster?: string;
  duration?: number;
  title?: string;
  items?: FolderItem[];   // gallery and folder
}

FolderItem#

ts
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#

ts
export type CardType = "approval" | "question" | "preview" | "status" | "note";

CardState#

ts
export type CardState = "open" | "answered" | "expired" | "withdrawn" | "done";

Action#

ts
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#

ts
export type FieldKind = "text" | "textarea" | "choice" | "multichoice" | "number" | "date" | "toggle";

Field#

ts
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#

ts
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#

ts
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#

ts
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.

ts
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.

ts
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).

ts
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#

ts
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#

ts
export interface MetricPoint {
  at: ISODate;
  value: number;
}

Metric#

ts
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.

ts
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#

ts
export type TileSize = "small" | "medium" | "large"; // 1x1, 2x1, 2x2 grid cells

TileSource#

What a tile shows. Exactly one shape per kind.

ts
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 shortcut

CardFilter#

ts
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#

ts
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#

ts
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.

ts
export interface BoardInput {
  name: string;
  icon?: string;
  position?: number;
  tiles: Omit<Tile, "id">[] | Tile[];
}

Accounts, projects, keys, rules#

Plan#

ts
export type Plan = "free" | "pro";

Limits#

ts
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#

ts
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#

ts
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#

ts
export type KeyScope = "write" | "board" | "delegate" | "admin";

ApiKey#

ts
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.

ts
export interface CreatedKey extends ApiKey {
  secret: string;                     // "afk_w_…" 40+ chars
}

Rule#

ts
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#

ts
export interface Session {
  token: string;                      // "afs_…" bearer for the apps
  account: Account;
  device: Device;
}

Device#

ts
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).

ts
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 };