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.

Apps

• POST
  Transfer an app between the caller and a team/api/v1/apps/{appId}/transfer
• PATCH
  Update signed-in app access/api/v1/apps/{appId}/signed-in-access
• GET
  Get an editable Template listing/api/v1/apps/{appId}/template-listing
• PATCH
  Update a Template listing draft/api/v1/apps/{appId}/template-listing
• POST
  Disable a Template/api/v1/apps/{appId}/template-listing/disable
• POST
  Enable a Template/api/v1/apps/{appId}/template-listing/enable
• POST
  Publish a Template listing/api/v1/apps/{appId}/template-listing/publish
• POST
  Unpublish a Template listing/api/v1/apps/{appId}/template-listing/unpublish
• GET
  Read an app build and its accepted source/api/v1/app-builds/{buildId}
• POST
  Cancel a pending app build/api/v1/app-builds/{buildId}/cancel
• GET
  Get an app’s activity timeline/api/v1/apps/{appId}/activity

TeamInvitations

• DELETE
  Cancel an outgoing team invitation/api/v1/team-invitations/{invitationId}
• POST
  Accept a team invitation/api/v1/team-invitations/{invitationId}/accept
• POST
  Decline a team invitation/api/v1/team-invitations/{invitationId}/decline
• POST
  Re-send a team invitation/api/v1/team-invitations/{invitationId}/resend
• POST
  Invite a user to a team by email/api/v1/teams/{teamId}/invitations

Teams

• GET
  List the caller’s teams/api/v1/teams
• POST
  Create a team/api/v1/teams
• GET
  Get team App defaults/api/v1/teams/{teamId}/app-defaults
• PATCH
  Update team App defaults/api/v1/teams/{teamId}/app-defaults
• GET
  List a team’s app inventory/api/v1/teams/{teamId}/apps
• GET
  Get a team’s audit trail/api/v1/teams/{teamId}/audit
• GET
  List a team’s egress ledger (declared hosts and API ops)/api/v1/teams/{teamId}/egress
• GET
  Get a team’s exposure summary/api/v1/teams/{teamId}/exposure
• GET
  List a team’s people/api/v1/teams/{teamId}/people
• GET
  List a team’s shares ledger/api/v1/teams/{teamId}/shares

TeamMembers

• POST
  Add a member to a team/api/v1/teams/{teamId}/members
• DELETE
  Leave a team/api/v1/teams/{teamId}/members/me
• PATCH
  Change a team member’s role/api/v1/teams/{teamId}/members/{memberId}
• DELETE
  Remove a member from a team/api/v1/teams/{teamId}/members/{memberId}

AppShares

• GET
  List an app’s direct shares/api/v1/apps/{appId}/shares
• POST
  Invite a user to an app/api/v1/apps/{appId}/shares
• PATCH
  Change an existing share’s role by grantee/api/v1/apps/{appId}/shares
• POST
  Accept a share invitation/api/v1/apps/{appId}/shares/accept
• POST
  Decline or leave a share/api/v1/apps/{appId}/shares/decline
• POST
  Revoke a share by grantee/api/v1/apps/{appId}/shares/revoke
• PATCH
  Change an existing share’s role/api/v1/apps/{appId}/shares/{shareId}
• POST
  Revoke a share/api/v1/apps/{appId}/shares/{shareId}/revoke

Widget

• GET
  Resolve a private runtime issue handoff/api/v1/widget/apps/{appId}/overview/handoffs/{token}

Operations

• POST
  Create an app or accept an ESM app build/app
• GET
  List your owned and shared apps, newest first/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
• POST
  Copy an app into a new private app owned by the caller/app/{id}/copy
• 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 starter prompt for people who copy this Template/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
• POST
  Create a new secret value/app/{id}/secrets
• PUT
  Create or replace a 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
• POST
  Upload an asset for an app/app/{id}/assets
• GET
  List assets 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
• POST
  Mint a personal access token (`chrm_user_*`)/api/token
• GET
  List the caller’s tokens (no plaintext, no hash)/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
• PATCH
  Update a Routine's interval or enabled state/api/v1/routines/{routineId}
• DELETE
  Delete a Routine/api/v1/routines/{routineId}
• GET
  List the caller's Webhooks/api/v1/webhooks
• POST
  Declare a Webhook on an app/api/v1/apps/{appId}/webhooks
• PATCH
  Rename a Webhook, change its enabled state, or rotate its secret/api/v1/webhooks/{webhookId}
• DELETE
  Delete a Webhook/api/v1/webhooks/{webhookId}
• POST
  Deliver an event to a Webhook/api/v1/hooks/{webhookId}
• 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