Charming API

Public HTTP surface for the Charming app runtime. The narrative agent guide lives at https://charm.ing/docs/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.

Operations

• GET
  List your owned and shared apps, newest first/app
• POST
  Create an app (anonymous or authenticated upsert)/app
• PUT
  Update an existing app/app/{id}
• DELETE
  Delete an app/app/{id}
• POST
  Call a declared app route or its unmatched-request fallback/app/{id}/api/{operation}
• POST
  Claim an unclaimed app for the authenticated user/app/{id}/claim
• GET
  Per-app OpenAPI document derived from `export const routes`/app/{id}/openapi.json
• GET
  Get an app's agent description without changing the app/app/{id}/agent.json
• GET
  Owner-only metadata + storage key inventory/app/{id}/describe
• GET
  Read the exact persisted source for an app/app/{id}/source
• PATCH
  Apply exact-string find/replace edits to the persisted source/app/{id}/source
• PUT
  Toggle Template copying and public listing/app/{id}/remixable
• PUT
  Toggle whether anyone can open the app with no login/app/{id}/public
• PUT
  Set or clear the authored chat-with-app starter prompt/app/{id}/starter-prompt
• PUT
  Set the home-screen / favicon icon (emoji + bg)/app/{id}/icon
• DELETE
  Clear the icon and fall back to the default icon/app/{id}/icon
• GET
  List the app secret NAMES (never values)/app/{id}/secrets
• PUT
  Create or replace a secret value/app/{id}/secrets
• POST
  Create a new secret value/app/{id}/secrets
• DELETE
  Delete a secret by name/app/{id}/secrets
• GET
  Read the app's durable runtime-failure events/app/{id}/activity
• GET
  Subscribe to the live-state SSE stream for an app/app/{id}/events
• GET
  Read the per-app runtime error ring buffer/app/{id}/diag
• POST
  Report a runtime error from the in-page shell (anonymous)/app/{id}/diag/report
• POST
  Report a caught app load failure from the in-page bridge (anonymous)/app/{id}/load-error/report
• POST
  Submit durable feedback for an app/app/{id}/feedback
• GET
  List assets for an app/app/{id}/assets
• POST
  Upload an asset for an app/app/{id}/assets
• DELETE
  Delete an asset/app/{id}/assets/{key}
• GET
  Resolve a manifestId to an appId in the caller’s scope/app/resolve/{manifestId}
• POST
  Mint a device_code for an unauthenticated agent (RFC 8628-shaped)/api/pair/start
• POST
  Poll a device_code until the user approves/api/pair/poll
• POST
  Approve a pairing (browser-side, signed-in user)/api/pair/approve
• GET
  List the caller’s tokens (no plaintext, no hash)/api/token
• POST
  Mint a personal access token (`chrm_user_*`)/api/token
• DELETE
  Revoke a token/api/token/{id}
• GET
  List the caller's Routines/api/v1/routines
• POST
  Schedule a Routine on an app/api/v1/apps/{appId}/routines
• DELETE
  Delete a Routine/api/v1/routines/{routineId}
• PATCH
  Update a Routine's interval or enabled state/api/v1/routines/{routineId}
• GET
  Fetch the canonical Charming authoring guide as Markdown/api/prompts/charming-app-guide
• GET
  Fetch the Charming design guide as Markdown/api/prompts/charming-design-guide
• GET
  This document/.well-known/openapi.json
• GET
  OAuth/MCP discovery metadata (delegated to better-auth)/.well-known/oauth-authorization-server
• GET
  OAuth authorization-server metadata for the ChatGPT MCP surface/.well-known/oauth-authorization-server/mcp/chatgpt
• GET
  Web Bot Auth signing-key directory (RFC 9421)/.well-known/http-message-signatures-directory
• GET
  OAuth protected-resource metadata (delegated to better-auth)/.well-known/oauth-protected-resource
• GET
  OAuth protected-resource metadata for the default MCP surface/.well-known/oauth-protected-resource/mcp
• GET
  OAuth protected-resource metadata for the ChatGPT MCP surface/.well-known/oauth-protected-resource/mcp/chatgpt
• GET
  OAuth protected-resource metadata for the inline MCP surface/.well-known/oauth-protected-resource/mcp/inline