Charming API

Public HTTP surface for the Charming app runtime. The narrative agent guide lives at https://usecharming.com/llms-full.txt; this spec is the machine-readable source of truth for routes, request/response shapes, and error kinds.

Timeout SLAs (info["x-charming-sla"] + per-operation x-charming-timeout-ms) are documentation only — they describe the targets the server tries to hit, not enforced ceilings. Use them to set sensible client read timeouts, not as hard guarantees. The x-buildy-* aliases are deprecated compatibility keys.

Operations

• GETList the authenticated user's apps — owned plus shared-with-them (newest first)/app
• POSTCreate an app (anonymous or authenticated upsert)/app
• PUTUpdate an existing app/app/{id}
• DELETEDelete an app/app/{id}
• POSTCall an operation defined inside the app's `fetch` handler/app/{id}/api/{operation}
• POSTClaim an unclaimed app for the authenticated user/app/{id}/claim
• GETPer-app OpenAPI document derived from `export const routes`/app/{id}/openapi.json
• GETCanonical per-app agent descriptor (side-effect-free)/app/{id}/agent.json
• GETOwner-only metadata + storage key inventory/app/{id}/describe
• GETRead the exact persisted source for an app/app/{id}/source
• PATCHApply exact-string find/replace edits to the persisted source/app/{id}/source
• PUTToggle whether visitors auto-fork their own copy of the app/app/{id}/remixable
• PUTToggle whether anyone can open the app with no login/app/{id}/public
• PUTSet or clear the authored chat-with-app starter prompt/app/{id}/starter-prompt
• PUTSet the home-screen / favicon icon (emoji + bg)/app/{id}/icon
• DELETEClear the icon and fall back to the default Charming mark/app/{id}/icon
• GETList the app secret NAMES (never values)/app/{id}/secrets
• PUTCreate or replace a secret value/app/{id}/secrets
• POSTCreate a new secret value/app/{id}/secrets
• DELETEDelete a secret by name/app/{id}/secrets
• GETRead the app's durable runtime-failure events/app/{id}/activity
• GETSubscribe to the live-state SSE stream for an app/app/{id}/events
• GETRead the per-app runtime error ring buffer/app/{id}/diag
• POSTReport a runtime error from the in-page shell (anonymous)/app/{id}/diag/report
• POSTReport a caught app load failure from the in-page bridge (anonymous)/app/{id}/load-error/report
• POSTSubmit durable feedback for an app/app/{id}/feedback
• GETList assets for an app/app/{id}/assets
• POSTUpload an asset for an app/app/{id}/assets
• DELETEDelete an asset/app/{id}/assets/{key}
• GETResolve a manifestId to an appId in the caller’s scope/app/resolve/{manifestId}
• POSTMint a device_code for an unauthenticated agent (RFC 8628-shaped)/api/pair/start
• POSTPoll a device_code until the user approves/api/pair/poll
• POSTApprove a pairing (browser-side, signed-in user)/api/pair/approve
• GETList the caller’s tokens (no plaintext, no hash)/api/token
• POSTMint a personal access token (`bld_user_*`)/api/token
• DELETERevoke a token/api/token/{id}
• GETFetch the canonical Charming authoring guide as Markdown/api/prompts/charming-app-guide
• GETFetch the Charming design guide as Markdown/api/prompts/charming-design-guide
• GETThis document/.well-known/openapi.json
• GETOAuth/MCP discovery metadata (delegated to better-auth)/.well-known/oauth-authorization-server
• GETWeb Bot Auth signing-key directory (RFC 9421)/.well-known/http-message-signatures-directory
• GETOAuth protected-resource metadata (delegated to better-auth)/.well-known/oauth-protected-resource