All pages
REST API
Base URL: https://api.craving.com/functions/v1/gc_marketplace_api. Every /v1/* request requires a Bearer install access token:
Authorization: Bearer crvat_…
X-Craving-API-Version: 2026-09-01All responses are JSON and include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Rate-limited requests return 429 with Retry-After (Rate limits). Errors return { "error": "<code>", "message": "…" } where error is one of unauthorized, invalid_token, installation_inactive, insufficient_scope, forbidden, invalid_request, unsupported_version, not_found, method_not_allowed, rate_limited, unavailable or server_error.
An install token can only access its own installation.
GET /v1/me
Requires scope profile.read. Returns the installation record, the installer’s public profile and, when the installation is an agency install with agency.read, the agency and its managed Residents (creators).
{
"installation": {
"id": "…",
"scope": "account",
"status": "active",
"chat_enabled": true,
"settings": { "layout": "grid" },
"connections": [],
"granted_scopes": ["profile.read"],
"installed_at": "2026-09-13T20:00:00Z"
},
"installer": {
"id": "…",
"username": "sophie",
"name": "Sophie",
"avatar": "https://…",
"is_creator": true
},
"agency": null
}GET /v1/installations/{id}
Requires scope profile.read. Returns the installation object above (404 if {id} does not match the token’s installation_id).
PATCH /v1/installations/{id}
Requires scope profile.read. Updates external connections badges and/or merges settings for the installation:
{
"connections": [
{ "provider": "calendly", "label": "sophie@calendly", "connected_at": "2026-09-13T20:05:00Z" }
],
"settings": { "layout": "list" }
}connections accepts up to 10 items (snake_case provider, label up to 80 characters) and displays them as Connected badges to the installer. settings is validated against your manifest’s block.settings_schema (422 invalid_request on validation failure) and merged into the installation’s settings.
POST /v1/usage-events
Requires scope payments.app. Reports a metered usage event for an active installation (or within 24 hours after an uninstall):
{
"meter": "order.placed",
"quantity": 1,
"idempotency_key": "order-8813",
"occurred_at": "2026-09-13T20:08:00Z"
}Returns 202 { "accepted": true, "duplicate": false, "event_id": "…", "meter": "order.placed" }, or 422 with error set to INSTALLATION_NOT_FOUND, UNKNOWN_METER, INVALID_QUANTITY (must be non-zero and at most 100,000), INVALID_IDEMPOTENCY_KEY (1 to 200 characters) or PERIOD_CLOSED (more than 24 hours after uninstall). Idempotent per (installation, idempotency_key). See Billing and payouts.
GET /v1/stats
Returns your app’s public store aggregates ({ "app": { "install_count": 42, "rating_avg": 4.8, "rating_count": 12 } }). Daily breakdowns live under Usage by day on your app page in craving Apps.
GET /v1/fans/{ref}
Requires scope fans.read. Returns the Visitor behind one of your app’s pseudonymous fan_… references (from subjects in a Resident event webhook or fan.ref in a chat tool invoke), as shown in the Resident’s Visitors list. Returns 404 if no Visitor of that Resident matches ref. On an agency installation, pass ?creator_id=<uuid> (carried on Resident event payloads).
{
"ref": "fan_4f1c…",
"creator_id": "…",
"name": "Alex",
"first_contact_at": "2026-08-01T12:00:00Z",
"last_activity_at": "2026-09-13T19:45:00Z",
"last_paid_at": "2026-09-10T14:20:00Z",
"lifetime_cents": 12900,
"subscribed": true
}GET /v1/earnings
Requires scope earnings.read. Returns the Resident’s net earnings in cents for today, the last 7 and 30 UTC days, and all time. On an agency installation, pass ?creator_id=<uuid>.
{
"creator_id": "…",
"currency": "USD",
"today_cents": 4700,
"last_7_days_cents": 31200,
"last_30_days_cents": 98100,
"lifetime_cents": 1240500
}GET /v1/home
Requires scope home.read. Returns the Resident’s Homes and their theme configuration. On an agency installation, pass ?creator_id=<uuid>.
{
"creator_id": "…",
"homes": [
{
"id": "…",
"slug": "sophie",
"name": "Main",
"title": "…",
"is_default": true,
"is_active": true,
"is_nsfw": false,
"theme": { "…": "…" },
"updated_at": "2026-09-13T18:00:00Z"
}
]
}POST /v1/blocks/refresh
Marks all cached documents for this installation’s drawn Home blocks as due for refresh on the next view. Returns how many cached documents were marked expired:
{ "expired": 2 }Sessions and JWKS
GET /.well-known/jwks.json: public JWK set used to verify ES256 installer session tokens.POST /block-sessions { "block_id" }andPOST /dashboard-sessions { "installation_id" }: internal endpoints called by craving’s web and mobile clients when opening an iframe.
Token and channel endpoints
POST https://api.craving.com/functions/v1/gc_marketplace_oauth/token: exchanges aninstall_codeorrefresh_token(Authentication).POST https://api.craving.com/functions/v1/gc_app_channel_event: receives signed inbound messages and history from a Channel connector.