All pages
Manifest
A version is a single JSON document validated when you save it, so schema mistakes surface in the portal before review. Its JSON Schema is manifest.json: point your editor or your tests at it to catch them sooner. The schema checks each field; what spans fields (a capability’s section and scope, every URL on a declared origin) is in its descriptions and checked on save.
{
"manifest_version": "1",
"capabilities": ["home_block", "chat_tools"],
"scopes": ["profile.read", "chat.tools", "earnings.read"],
"events": ["visitor.purchase"],
"origins": ["https://app.example.com"],
"post_install_redirect": "https://app.example.com/craving/installed",
"block": {
"url": "https://app.example.com/craving/block",
"height": { "mode": "fixed", "px": 320 },
"settings_schema": [
{ "id": "title", "type": "text", "label": "Title", "default": "My shelf" },
{ "id": "layout", "type": "select", "label": "Layout", "options": ["grid", "list"] },
{ "id": "show_prices", "type": "toggle", "label": "Show prices", "default": true }
]
},
"dashboard": { "url": "https://app.example.com/craving/dashboard" },
"tools": [
{
"name": "lookup_item",
"description": "Look up an item by name and return its price and link.",
"parameters": {
"type": "object",
"properties": { "query": { "type": "string" } },
"required": ["query"]
},
"invoke_url": "https://app.example.com/craving/tools/lookup_item",
"timeout_ms": 5000
}
],
"channel": {
"platform": "discord",
"display_name": "Discord",
"icon": "https://app.example.com/discord.png",
"send_url": "https://app.example.com/craving/channel/send",
"history_url": "https://app.example.com/craving/channel/history",
"capabilities": ["text", "images", "links"]
}
}Top level
| Field | Required | Notes |
|---|---|---|
manifest_version | no | Always "1". |
capabilities | yes | One or more of home_block, chat_tools, embedded_dashboard, usage_meters, fan_charges, agency_install, chat_channel. |
scopes | yes | Permissions the installer grants. Must match your declared capabilities (see table below). |
events | no | Resident events you want delivered (Webhooks). Each event’s required scope must be in scopes. |
origins | when framed or called | Up to 10 https:// origins (no path). Required for home_block, embedded_dashboard, chat_tools and chat_channel. Every endpoint and frame URL in block, dashboard, tools and channel must sit on one of them. |
post_install_redirect | no | https:// URL where the browser may be sent after an install. |
Scopes and consistency
| Scope | What the installer sees | Capability rules |
|---|---|---|
profile.read | See your public profile (username, name, avatar) | Needed for GET /v1/me and /v1/installations/{id} |
home.read / home.write | Read your Home theme and where its block is placed / Update the settings of its own Home block | |
chat.tools | Answer questions craving AI asks it in your chats | Required by chat_tools |
chat.read / chat.write | Read your chat messages / Send messages in your chats | Needs chat_tools or chat_channel; heavy |
fans.read | See which Visitors it is talking to | heavy |
earnings.read | See your earnings totals | |
payments.app | Report usage and read its own invoices | Required by usage_meters and fan_charges |
agency.read / agency.write | See the Residents of your agency / Change agency-wide settings | agency_install requires agency.read; agency.write requires agency_install and is heavy |
chat.transport | Deliver and receive Visitor messages on its platform | Required by chat_channel; heavy |
Heavy scopes (chat.read, chat.write, fans.read, agency.write, chat.transport) and heavy capabilities (fan_charges, chat_channel) require human review before a version goes live. Request only the scopes your app needs so the consent sheet stays short.
events
Optional array of Resident event kinds from the table on Webhooks. Each event requires its matching scope in scopes (for example, visitor.purchase requires earnings.read, request.created requires fans.read and home.review_decided requires home.read). Adding a new event kind to a live app prompts existing installers to re-consent in Your apps before their installation moves to the new version.
block
Required with home_block. Set render to "frame" (default) or "json" (Drawn blocks):
- Framed (
"frame"): requiresurlon a declared origin. Optionalheight:modeis"fixed"(pxfrom 40 to 1200),"aspect"(ratiosuch as"16:9") or"auto"(default; optionalestimated_px, and the frame postscraving:resize). - Drawn (
"json"): requirescontent_urlon a declared origin. Optionalaction_url(on a declared origin, wherechoicevotes are POSTed) andrefresh_seconds(300 to 86400, default 3600). settings_schema: optional array of up to 30 fields. Each field has a uniquesnake_caseid(up to 40 characters), atype(text,textarea,url,number,select,toggle,color,image,datetime,timezone,list), alabel(1 to 60 characters), and optionalrequired,defaultandhelp.select: requires 1 to 30options(strings or{ value, label }).datetime: an ISO 8601 timestamp with its UTC offset, entered in the Resident’s local time.timezone: an IANA time zone name (such asEurope/Brussels), pre-filled from the Resident’s device when they first pick adatetime.list: repeated items with 1 to 8 sub-fields infields(text,textarea,url,number,datetime,toggle, each with a uniquesnake_caseidand alabelof 1 to 60 characters), optionalmax_items(1 to 50, default 20) and optionalitem_label. Each saved item keeps a stableid.
dashboard
Required with embedded_dashboard: { "url": "https://…" } on a declared origin, framed on the installer’s app page in Your apps with a 60-minute dashboard session token.
tools
Required with chat_tools: 1 to 8 tools. Each tool has a unique snake_case name (3 to 48 characters), a description (10 to 400 characters, read by craving AI to decide when to call it), a JSON Schema parameters object (type: "object"), an invoke_url on a declared origin and optional timeout_ms (500 to 8000, default 8000). See Chat tools.
channel
Required with chat_channel: platform (snake_case, 2 to 31 characters), display_name (2 to 40 characters), optional icon (https:// URL), send_url and history_url on a declared origin, and capabilities (an array containing "text", plus any of "images", "audio", "links", "paid_links", "typing", "read_receipts"). See Channel connectors.