Submit durable feedback for an app

Owner-only durable feedback ingest. Auth posture matches GET /app/{id}/diag (requireAppAccess): app token, user token, render token, or claim cookie. Body is capped at 96 KiB wire / 16 KiB text / 64 KiB serialized structuredData. The MCP submit_feedback tool forces source="agent" server-side; direct REST callers may set source to user or auto-crash.

POST/app/{id}/feedback

Authorization

AuthorizationBearer token (bld_app_*) · headerrequired

Per-app token returned once by `POST /app` for anonymous creates. Authorises mutations and `/api/*` calls on that one app only.

AuthorizationBearer token (bld_user_*) · headerrequired

User-scoped personal access token. Mint via `POST /api/token` after signing in, or via the device-pairing flow at `POST /api/pair/start`. Authorises everything the user can do.

AuthorizationBearer token (bld_render_*) · headerrequired

Short-lived per-app token used by null-origin sandboxed iframes (Claude Desktop, ChatGPT Apps) to call back into the app without cookies. Minted server-side at render time and embedded in the runtime closure; not user-mintable. Bound to one app id.

Path parameters

idstringrequired

Request body

requiredapplication/json

categorystringrequired

Feedback category. `crash` requires `crashData` (or its snake_case alias) carrying at least `message`.

Allowed:bugcrashenhancementpraiseother

sourcestring

Optional origin tag. Defaults to `user`. The MCP `submit_feedback` tool forces `agent` server-side; direct REST callers may pass `user` / `auto-crash` explicitly.

Allowed:useragentauto-crash

textstring

Free-form feedback body. 16384-character cap; oversize bodies return `text_too_large` (413).

max length 16384

structuredDataobject

Caller-supplied JSON payload (e.g. route, repro inputs). Serialized payload is capped at 65536 bytes; oversize payloads return `structured_data_too_large` (413). Snake_case alias `structured_data` is also accepted.

crashDataobject

Crash details. Required when `category=crash`; optional otherwise. Snake_case alias `crash_data` is also accepted.

Show properties

messagestringrequired

stackstring

urlstring

userAgentstring

traceIdstring

Responses

201Feedback recorded.

okbooleanrequired

Allowed:true

valueobjectrequired

Show properties

idstring<uuid>required

createdAtstring<date-time>required

400Invalid app id, malformed body, or category=crash without crashData.

okbooleanrequired

Allowed:false

errorobjectrequired

Show properties

kindstringrequired

Stable enum-shaped error key. Branch on this for recovery flows.

Allowed:not_foundunknown_operationoperation_not_foundoperation_failedunauthorizedtoken_expiredforbiddenforbidden_writestorage_quota_exceededinvalid_moduleinvalid_uiinvalid_route_schemainvalid_routes_shapeinvalid_manifest_exportsinvalid_requestinvalid_inputinvalid_outputunexpected_keyscapability_deniedcapability_errorexecutor_errorinvalid_call_shapealready_claimedduplicate_remixmanifest_not_foundpayload_too_largemodule_too_largeui_too_largedescription_too_longmissing_descriptioninvalid_descriptionrate_limitedtoo_many_requestsexpiredalready_approvedanon_not_remixableinvalid_if_matchprecondition_requiredversion_mismatchold_string_not_foundold_string_not_uniqueedits_too_largemanifest_id_conflictmanifest_id_immutabletext_too_largestructured_data_too_largeapp_not_foundasset_too_largeasset_count_exceededasset_quota_exceededasset_invalid_keyasset_invalid_content_typeasset_errorinvalid_idsse_cookie_expiredinvalid_secret_namesecret_too_largesecret_already_existsinvalid_iconteam_slug_takenalready_membergrantee_not_foundinvite_cap_reachedread_onlyhandle_takeninvalid_handlename_takenapp_unclaimedlink_cap_reachedgrantee_is_owneralready_invited

messagestring

reasonstring

Set on 401s to distinguish token failure modes when finer detail is needed. `token_revoked_post_claim` is the post-#1284 surface for a bld_app_* that was invalidated by a claim — the `recovery` field on the same `error` object carries the self-contained pairing-recovery hint the agent should follow instead of creating a new app.

Allowed:token_malformedtoken_unknowntoken_revokedtoken_revoked_post_claim

Self-contained recovery hint, branching on `kind`. Attached to error envelopes the agent can self-correct on: `pair` for `token_revoked_post_claim` 401s (#1284), `retry` for 429s, `shrink` for too-large / quota-exceeded 413s, `refetch` for 412 `version_mismatch` / `invalid_if_match` / 428 `precondition_required`, `fix_route_label` for 403 `forbidden_write`, `open_existing` for 409 `duplicate_remix`, and `rename` for 409 `manifest_id_immutable` / `manifest_id_conflict`. Every `instructions` string is a single-paragraph, action-first walk-through. Inlined per ADR 2026-05-06-agent-facing-error-surfaces-self-contain-the-fix.

Show properties

One of:

RecoveryPair

kindstringrequired

Allowed:pair

startstring<uri>required

verification_urlstring<uri>required

instructionsstringrequired

RecoveryRetry

kindstringrequired

Allowed:retry

retry_after_secintegerrequired

Seconds to wait before retrying. Matches the `RateLimit-Reset` and `Retry-After` headers on the same response.

min 0

retry_after_urlstring<uri>required

Absolute URL to retry verbatim once the wait elapses.

instructionsstringrequired

RecoveryShrink

kindstringrequired

Allowed:shrink

fieldstringrequired

Which input tripped the cap.

Allowed:moduleuistylesdescriptiontextstructured_dataasseteditssecretpayload

size_bytesintegerrequired

min 0

cap_bytesintegerrequired

min 0

instructionsstringrequired

RecoveryRefetch

kindstringrequired

Allowed:refetch

refetch_urlstring<uri>required

Absolute URL to GET for the fresh ETag before retrying with a corrected If-Match.

instructionsstringrequired

RecoveryFixRouteLabel

kindstringrequired

Allowed:fix_route_label

instructionsstringrequired

App-code recovery: the fix is in the route declaration, NOT in the request. Retrying the same request will fail again.

RecoveryOpenExisting

kindstringrequired

Allowed:open_existing

existing_app_idstringrequired

existing_urlstring<uri>required

instructionsstringrequired

RecoveryRename

kindstringrequired

Allowed:rename

instructionsstringrequired

401Authentication required.

okbooleanrequired

Allowed:false

errorobjectrequired

Show properties

kindstringrequired

Stable enum-shaped error key. Branch on this for recovery flows.

messagestring

reasonstring

Allowed:token_malformedtoken_unknowntoken_revokedtoken_revoked_post_claim

Show properties

One of:

RecoveryPair

kindstringrequired

Allowed:pair

startstring<uri>required

verification_urlstring<uri>required

instructionsstringrequired

RecoveryRetry

kindstringrequired

Allowed:retry

retry_after_secintegerrequired

Seconds to wait before retrying. Matches the `RateLimit-Reset` and `Retry-After` headers on the same response.

min 0

retry_after_urlstring<uri>required

Absolute URL to retry verbatim once the wait elapses.

instructionsstringrequired

RecoveryShrink

kindstringrequired

Allowed:shrink

fieldstringrequired

Which input tripped the cap.

Allowed:moduleuistylesdescriptiontextstructured_dataasseteditssecretpayload

size_bytesintegerrequired

min 0

cap_bytesintegerrequired

min 0

instructionsstringrequired

RecoveryRefetch

kindstringrequired

Allowed:refetch

refetch_urlstring<uri>required

Absolute URL to GET for the fresh ETag before retrying with a corrected If-Match.

instructionsstringrequired

RecoveryFixRouteLabel

kindstringrequired

Allowed:fix_route_label

instructionsstringrequired

App-code recovery: the fix is in the route declaration, NOT in the request. Retrying the same request will fail again.

RecoveryOpenExisting

kindstringrequired

Allowed:open_existing

existing_app_idstringrequired

existing_urlstring<uri>required

instructionsstringrequired

RecoveryRename

kindstringrequired

Allowed:rename

instructionsstringrequired

403Token does not authorize this app.

okbooleanrequired

Allowed:false

errorobjectrequired

Show properties

kindstringrequired

Stable enum-shaped error key. Branch on this for recovery flows.

messagestring

reasonstring

Allowed:token_malformedtoken_unknowntoken_revokedtoken_revoked_post_claim

Show properties

One of:

RecoveryPair

kindstringrequired

Allowed:pair

startstring<uri>required

verification_urlstring<uri>required

instructionsstringrequired

RecoveryRetry

kindstringrequired

Allowed:retry

retry_after_secintegerrequired

Seconds to wait before retrying. Matches the `RateLimit-Reset` and `Retry-After` headers on the same response.

min 0

retry_after_urlstring<uri>required

Absolute URL to retry verbatim once the wait elapses.

instructionsstringrequired

RecoveryShrink

kindstringrequired

Allowed:shrink

fieldstringrequired

Which input tripped the cap.

Allowed:moduleuistylesdescriptiontextstructured_dataasseteditssecretpayload

size_bytesintegerrequired

min 0

cap_bytesintegerrequired

min 0

instructionsstringrequired

RecoveryRefetch

kindstringrequired

Allowed:refetch

refetch_urlstring<uri>required

Absolute URL to GET for the fresh ETag before retrying with a corrected If-Match.

instructionsstringrequired

RecoveryFixRouteLabel

kindstringrequired

Allowed:fix_route_label

instructionsstringrequired

App-code recovery: the fix is in the route declaration, NOT in the request. Retrying the same request will fail again.

RecoveryOpenExisting

kindstringrequired

Allowed:open_existing

existing_app_idstringrequired

existing_urlstring<uri>required

instructionsstringrequired

RecoveryRename

kindstringrequired

Allowed:rename

instructionsstringrequired

404App not found.

okbooleanrequired

Allowed:false

errorobjectrequired

Show properties

kindstringrequired

Stable enum-shaped error key. Branch on this for recovery flows.

messagestring

reasonstring

Allowed:token_malformedtoken_unknowntoken_revokedtoken_revoked_post_claim

Show properties

One of:

RecoveryPair

kindstringrequired

Allowed:pair

startstring<uri>required

verification_urlstring<uri>required

instructionsstringrequired

RecoveryRetry

kindstringrequired

Allowed:retry

retry_after_secintegerrequired

Seconds to wait before retrying. Matches the `RateLimit-Reset` and `Retry-After` headers on the same response.

min 0

retry_after_urlstring<uri>required

Absolute URL to retry verbatim once the wait elapses.

instructionsstringrequired

RecoveryShrink

kindstringrequired

Allowed:shrink

fieldstringrequired

Which input tripped the cap.

Allowed:moduleuistylesdescriptiontextstructured_dataasseteditssecretpayload

size_bytesintegerrequired

min 0

cap_bytesintegerrequired

min 0

instructionsstringrequired

RecoveryRefetch

kindstringrequired

Allowed:refetch

refetch_urlstring<uri>required

Absolute URL to GET for the fresh ETag before retrying with a corrected If-Match.

instructionsstringrequired

RecoveryFixRouteLabel

kindstringrequired

Allowed:fix_route_label

instructionsstringrequired

App-code recovery: the fix is in the route declaration, NOT in the request. Retrying the same request will fail again.

RecoveryOpenExisting

kindstringrequired

Allowed:open_existing

existing_app_idstringrequired

existing_urlstring<uri>required

instructionsstringrequired

RecoveryRename

kindstringrequired

Allowed:rename

instructionsstringrequired

413Body exceeds the 96 KiB wire cap, `text` exceeds 16 KiB, or `structuredData` exceeds 64 KiB serialized. Error kinds: `payload_too_large`, `text_too_large`, `structured_data_too_large`.

okbooleanrequired

Allowed:false

errorobjectrequired

Show properties

kindstringrequired

Stable enum-shaped error key. Branch on this for recovery flows.

messagestring

reasonstring

Allowed:token_malformedtoken_unknowntoken_revokedtoken_revoked_post_claim

Show properties

One of:

RecoveryPair

kindstringrequired

Allowed:pair

startstring<uri>required

verification_urlstring<uri>required

instructionsstringrequired

RecoveryRetry

kindstringrequired

Allowed:retry

retry_after_secintegerrequired

Seconds to wait before retrying. Matches the `RateLimit-Reset` and `Retry-After` headers on the same response.

min 0

retry_after_urlstring<uri>required

Absolute URL to retry verbatim once the wait elapses.

instructionsstringrequired

RecoveryShrink

kindstringrequired

Allowed:shrink

fieldstringrequired

Which input tripped the cap.

Allowed:moduleuistylesdescriptiontextstructured_dataasseteditssecretpayload

size_bytesintegerrequired

min 0

cap_bytesintegerrequired

min 0

instructionsstringrequired

RecoveryRefetch

kindstringrequired

Allowed:refetch

refetch_urlstring<uri>required

Absolute URL to GET for the fresh ETag before retrying with a corrected If-Match.

instructionsstringrequired

RecoveryFixRouteLabel

kindstringrequired

Allowed:fix_route_label

instructionsstringrequired

App-code recovery: the fix is in the route declaration, NOT in the request. Retrying the same request will fail again.

RecoveryOpenExisting

kindstringrequired

Allowed:open_existing

existing_app_idstringrequired

existing_urlstring<uri>required

instructionsstringrequired

RecoveryRename

kindstringrequired

Allowed:rename

instructionsstringrequired

429Rate limit exceeded (30/min/app/ip, 200/min/app).

okbooleanrequired

Allowed:false

errorobjectrequired

Show properties

kindstringrequired

Stable enum-shaped error key. Branch on this for recovery flows.

messagestring

reasonstring

Allowed:token_malformedtoken_unknowntoken_revokedtoken_revoked_post_claim

Show properties

One of:

RecoveryPair

kindstringrequired

Allowed:pair

startstring<uri>required

verification_urlstring<uri>required

instructionsstringrequired

RecoveryRetry

kindstringrequired

Allowed:retry

retry_after_secintegerrequired

Seconds to wait before retrying. Matches the `RateLimit-Reset` and `Retry-After` headers on the same response.

min 0

retry_after_urlstring<uri>required

Absolute URL to retry verbatim once the wait elapses.

instructionsstringrequired

RecoveryShrink

kindstringrequired

Allowed:shrink

fieldstringrequired

Which input tripped the cap.

Allowed:moduleuistylesdescriptiontextstructured_dataasseteditssecretpayload

size_bytesintegerrequired

min 0

cap_bytesintegerrequired

min 0

instructionsstringrequired

RecoveryRefetch

kindstringrequired

Allowed:refetch

refetch_urlstring<uri>required

Absolute URL to GET for the fresh ETag before retrying with a corrected If-Match.

instructionsstringrequired

RecoveryFixRouteLabel

kindstringrequired

Allowed:fix_route_label

instructionsstringrequired

App-code recovery: the fix is in the route declaration, NOT in the request. Retrying the same request will fail again.

RecoveryOpenExisting

kindstringrequired

Allowed:open_existing

existing_app_idstringrequired

existing_urlstring<uri>required

instructionsstringrequired

RecoveryRename

kindstringrequired

Allowed:rename

instructionsstringrequired

Request

curl -X POST "https://charm.ing/app/string/feedback" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "bug",
  "source": "user",
  "text": "string",
  "structuredData": {},
  "crashData": {
    "message": "string",
    "stack": "string",
    "url": "string",
    "userAgent": "string",
    "traceId": "string"
  }
}'

const response = await fetch("https://charm.ing/app/string/feedback", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "category": "bug",
  "source": "user",
  "text": "string",
  "structuredData": {},
  "crashData": {
    "message": "string",
    "stack": "string",
    "url": "string",
    "userAgent": "string",
    "traceId": "string"
  }
})
});

import requests

response = requests.post(
    "https://charm.ing/app/string/feedback",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={
  "category": "bug",
  "source": "user",
  "text": "string",
  "structuredData": {},
  "crashData": {
    "message": "string",
    "stack": "string",
    "url": "string",
    "userAgent": "string",
    "traceId": "string"
  }
},
)

Response

{
  "ok": true,
  "value": {
    "id": "<uuid>",
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

{
  "ok": false,
  "error": {
    "kind": "not_found",
    "message": "string",
    "reason": "token_malformed",
    "recovery": {
      "kind": "pair",
      "start": "<uri>",
      "verification_url": "<uri>",
      "instructions": "string"
    }
  }
}

{
  "ok": false,
  "error": {
    "kind": "not_found",
    "message": "string",
    "reason": "token_malformed",
    "recovery": {
      "kind": "pair",
      "start": "<uri>",
      "verification_url": "<uri>",
      "instructions": "string"
    }
  }
}

{
  "ok": false,
  "error": {
    "kind": "not_found",
    "message": "string",
    "reason": "token_malformed",
    "recovery": {
      "kind": "pair",
      "start": "<uri>",
      "verification_url": "<uri>",
      "instructions": "string"
    }
  }
}

{
  "ok": false,
  "error": {
    "kind": "not_found",
    "message": "string",
    "reason": "token_malformed",
    "recovery": {
      "kind": "pair",
      "start": "<uri>",
      "verification_url": "<uri>",
      "instructions": "string"
    }
  }
}

{
  "ok": false,
  "error": {
    "kind": "not_found",
    "message": "string",
    "reason": "token_malformed",
    "recovery": {
      "kind": "pair",
      "start": "<uri>",
      "verification_url": "<uri>",
      "instructions": "string"
    }
  }
}

{
  "ok": false,
  "error": {
    "kind": "not_found",
    "message": "string",
    "reason": "token_malformed",
    "recovery": {
      "kind": "pair",
      "start": "<uri>",
      "verification_url": "<uri>",
      "instructions": "string"
    }
  }
}