Skip to content
Charming Docs
Esc
↑↓navigate↵open⌘Jpreview

Read the exact persisted source for an app

Returns the stored module, ui, and styles exactly as persisted, plus the resolved metadata envelope. Requires a real bearer token for the app or its owning user; render tokens and claim cookies are rejected. Response carries an ETag: "v<N>" header tracking appModules.currentVersion; pass it back as If-Match on PUT or PATCH to gate optimistic concurrency.

GET/app/{id}/source
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.
or
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.
Path parameters
idstringrequired
Responses
200Exact persisted source payload
idstring<uuid>required
urlstring<uri>required
manifestIdstringrequired
sourceManifestIdstringrequired
displayNamestringrequired
descriptionstring | nullrequired
versionMonotonicVersionrequired
Monotonic per-app version (`appModules.currentVersion`). The optimistic-concurrency primitive: new rows seed at 1 and bump on every successful write; truly-legacy pre-migration rows read 0. Pass back as `If-Match: "v<N>"` (REST) or `expected_version` (MCP) to gate edits.
min 0
appVersionstringrequired
Author-declared version string for the app (whatever the manifest source set as `manifest.version`, e.g. '0.0.1'). Distinct from the concurrency `version` int and from `manifestVersion`.
manifestVersionstringrequired
Charming manifest contract date (`YYYY-MM-DD`) the app is pinned to. The runtime branches on this value to pick contract-specific behaviour.
capabilitiescapabilitiesrequired
Show properties
capabilities
claimedbooleanrequired
expiresAtstring<date-time> | nullrequired
sourceobjectrequired
Show properties
modulestringrequired
uistring | nullrequired
stylesstring | nullrequired
401Authentication required.
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
recoveryRecoveryPair | RecoveryRetry | RecoveryShrink | RecoveryRefetch | RecoveryFixRouteLabel | RecoveryOpenExisting | RecoveryRename
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
403Token does not authorize this app.
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
recoveryRecoveryPair | RecoveryRetry | RecoveryShrink | RecoveryRefetch | RecoveryFixRouteLabel | RecoveryOpenExisting | RecoveryRename
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
404App not found.
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
recoveryRecoveryPair | RecoveryRetry | RecoveryShrink | RecoveryRefetch | RecoveryFixRouteLabel | RecoveryOpenExisting | RecoveryRename
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
Request
curl -X GET "https://charm.ing/app/string/source" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
{
  "id": "<uuid>",
  "url": "<uri>",
  "manifestId": "string",
  "sourceManifestId": "string",
  "displayName": "string",
  "description": "string",
  "version": 0,
  "appVersion": "string",
  "manifestVersion": "string",
  "capabilities": null,
  "claimed": true,
  "expiresAt": "2024-01-01T00:00:00Z",
  "source": {
    "module": "string",
    "ui": "string",
    "styles": "string"
  }
}