All pages
craving developer documentation
Apps extend what a Resident’s account can do. A Resident (or an agency, for every Resident it manages) installs your app on craving. From then on your app can render a block on their Home, give craving AI tools for their chats, open an embedded dashboard, and connect a chat channel so Visitors on another platform reach their inbox. Money always moves on craving.
The quickest app is a drawn block: one endpoint on your server answers a small JSON document, and craving draws it on the Home in the Home’s own style. The Quickstart builds one.
How an install works
- A Resident taps Install on your listing (or an agency operator taps Install for your agency) and approves the scopes and Resident events your manifest declares.
- craving activates the installation (right away for free plans, or once checkout settles for paid plans) and POSTs
installation.createdto your webhook with a one-time install code. - Your server exchanges that code at the token endpoint for an access token (valid for 1 hour) and a refresh token, scoped to the exact grant.
- From there you call the REST API for that installation, while framed Home blocks and dashboards receive short-lived session tokens that identify the installer.
Your app connects to external platforms on its own using your OAuth flows, tokens and storage. craving tells you who installed your app and what they approved.
The three identity tiers
| Tier | What it is | Where you get it |
|---|---|---|
| Settings only | The installer’s answers to your settings_schema, stored on craving and passed to your block. | settings in the session token, content_url POST body and GET /v1/me |
| Installer session | An ES256 JWT naming the installation, the installer’s public profile and the block. Verify it against our JWKS. | The craving_session fragment on your framed block or dashboard URL |
| Install token | A bearer token for calling the REST API on one installation with its granted scopes. | The token endpoint (install_code, then refresh_token) |
A drawn block only needs the first tier; most framed blocks need the first two. Apps that read or write craving data (chat tools, usage billing, agency reads, channel connectors) use the third.
JSON Schemas
The manifest and the drawn block document have JSON Schemas, for your editor, your tests and your agent: manifest.json and block-document.json.
Where to go next
- Quickstart: a drawn block, live on your own Home.
- Getting started: go from developer application to a live listing.
- Manifest: every field your version can declare.
- Authentication: request signatures, session JWTs and install tokens.
- Rate limits: how 429 backoff works and the reference client to ship.
- Listing requirements: what the automated review checks and when a person reviews your submission.