Skip to content
Esc
↑↓navigate↵open⌘Jpreview

Read an app build and its accepted source

Read progress or the retained terminal result using current user source access. Set include_source=true to inspect the exact accepted input. Only published means the app is live. Status stays readable after the build finishes. Accept: text/html renders progress and terminal results; pending pages refresh this status resource and published pages redirect to the actual app URL.

GET/api/v1/app-builds/{buildId}
Authorization
AuthorizationBearer token (chrm_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. Accepted by every operation that lists userToken in its security; operations that list only sessionCookie refuse it with 401 unauthorized.

Path parameters
buildIdstringrequired
Query parameters
include_sourceboolean
Responses
200

Current build operation.

okbooleanrequired
Allowed:true
buildIdstringrequired
intentstringrequired
Allowed:createupdatemigraterestorecopy
statestringrequired
Allowed:queuedresolvingbuildingvalidatingpublishedfailedsupersededcanceledexpired
sourceEtagstringrequired

The ETag of the revision this build saved once an App exists, usable as If-Match on the next save. It doesn't change after a later save; GET /app/{id}/source returns the current one. Before a creation publishes, the digest of the accepted input.

statusUrlstring<uri>required
retryAfterSecondsinteger
appIdstring<uuid>
revisioninteger

Published app source revision. Present only after successful publication.

min 1
desiredRevisioninteger
activeRevisioninteger
urlstring<uri>
attemptsintegerrequired
acceptedAtstring<date-time>required
updatedAtstring<date-time>required
finishedAtstring<date-time> | nullrequired
elapsedMsintegerrequired
lockStatestringrequired
Allowed:lockedunresolved
inputDigeststringrequired
lockDigeststring
resolvedDependenciesobject

Exact versions of the top-level npm packages the retained lock installs, by package name. Absent while the build is unresolved and for builds whose lock predates the package resolution.

queueDeadlinestring<date-time>required
deadlinestring<date-time>required
inspectionExpiresAtstring<date-time> | nullrequired
idempotencyExpiresAtstring<date-time> | nullrequired
sourceobject

The exact accepted package tree, when include_source=true and the inspection window is open.

Show properties
filesobjectrequired
errorobject
Show properties
kindstringrequired
messagestringrequired
retryablebooleanrequired
detailsobject
Show properties
Any of:
object
executionstringrequired
Allowed:not_startedmay_have_run
operationIdstringrequired
min length 1
reservationIdstring
min length 1
object
executionstringrequired
Allowed:may_have_run
stagestring

A stage only when the author's package caused the failure. source: the package was refused (its files, imports, or package.json, a size cap, a refused connect-src origin, a package name another App holds or that differs from the App's, or accepted source the current contract refuses); fix what the message names, in the file path names when given. dependencies: npm could not resolve or install the declared dependencies, or the tree has more packages than the limit; fix the package specifier names when given, its range in package.json, or trim the dependencies. compile: the compiler, or the check of the built server module, refused the App's code; fix the file and position named when given. Every other failure has no stage, because nothing in the package would fix it: a build sandbox, provider, executor, or database failing, a busy host, a cancellation, lost authority, an expired build or one that used up its attempts, an input Charming could not load, or a copy whose requested manifest id was taken. Save again.

Allowed:sourcedependenciescompile
targetstring
specifierstring
pathstring

The App file the failure points at, relative to the package root, when it points at one of the App's own files.

lineinteger

The 1-based line in path.

columninteger

The 1-based column in line.

303

Browser navigation to the actual published app URL.

400

Invalid source inclusion query.

okbooleanrequired
Allowed:false
errorobjectrequired
Show properties
kindstringrequired

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

Allowed:not_foundunknown_operationoperation_not_foundmethod_not_allowedoperation_failedtimeoutapp_busyvisitor_rate_limitedservice_busyunauthorizedsign_in_requiredtoken_expiredforbiddenaccount_not_joinedstaff_onlytwo_factor_requiredreauthentication_requiredforbidden_writeview_as_read_onlyemail_not_verifiedemail_needs_sign_instored_value_too_largestorage_fulltoo_many_keysstorage_method_unavailableinvalid_moduleinvalid_uiinvalid_filesbearer_requiredunpinned_cdn_scriptinvalid_route_schemainvalid_routes_shapecontract_migration_requiredinvalid_manifest_schemainvalid_manifest_exportsinvalid_requestinvalid_inputinvalid_outputunexpected_keyscapability_deniedcapability_errorexecutor_errorinvalid_call_shapealready_claimedmanifest_not_foundpayload_too_largemodule_too_largeui_too_largestyles_too_largedescription_too_longmissing_descriptioninvalid_descriptionrate_limitedimage_origin_deniedtoo_many_requestsexpiredalready_approvedanon_not_remixabletemplate_listing_incompletetemplate_media_invalidtemplate_listing_too_largeforbidden_template_editinvalid_if_matchprecondition_requiredexpected_revision_requiredidempotency_key_requiredidempotency_conflictapp_build_capacityapp_build_failedapp_build_expiredapp_build_authority_lostapp_build_unavailableapp_build_unsupportedversion_history_unavailableversion_not_restorablerevision_mismatchinvalid_revisioncandidate_effects_unsupportedold_string_not_foundold_string_not_uniqueinvalid_bucketbucket_unsetempty_editsedits_too_largemanifest_id_conflictmanifest_id_immutabletext_too_largestructured_data_too_largeapp_not_foundfeedback_not_foundfeedback_has_no_reply_recipientasset_too_largeasset_count_exceededasset_quota_exceededasset_invalid_keyasset_invalid_content_typeasset_errorinvalid_idsse_cookie_expiredinvalid_secret_namesecret_too_largesecret_already_existssecret_not_foundinvalid_iconteam_slug_takenalready_membertwo_factor_requiredrecent_login_requiredgrantee_not_foundinvite_cap_reachedinvite_sender_blockedrole_above_owninvite_delegation_owner_onlynot_your_inviteread_onlyhandle_takeninvalid_handlename_takeninvalid_domaindomain_takendomain_existsdomain_provider_unavailableapp_unclaimedlink_cap_reachedgrantee_is_ownergrantee_is_selfgrantee_already_has_accessalready_invitedroutine_limit_exceededinvalid_intervalop_requires_inputduplicate_routinewebhook_limit_exceededduplicate_webhookwebhook_disabledversion_limit_exceededplan_requiredconnector_call_limit_exceededconnector_rate_limitedconnector_not_grantedconnector_action_not_declaredconnector_no_personconnector_reconnect_requiredconnector_unavailableconnector_tool_failedconnector_cross_siteconnector_blocked_by_teamconnector_route_not_declaredconnector_function_not_approvedconnector_version_retiredconnector_holder_onlystorage_limit_exceededcopy_data_forbiddencopy_data_too_large
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 chrm_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
planstring

Present on every plan refusal: the tier the caller was refused under. Its presence is what marks an error as a plan refusal rather than a validation or permission failure.

Allowed:freeprobusinessenterprise
limitstring | integer

Which ceiling the call met, keyed by kind. A plan refusal (*_limit_exceeded) names the countable that ran out — version_history, routines_per_app, routines_per_owner, webhooks_per_app, webhooks_per_owner, connector_calls_per_month — and pairs it with max. An app_busy refusal names the bound it met and pairs it with observed and allowed; no plan lifts any of them. Two are per-app run bounds, concurrent_runs and runs_per_window; the third, render_token_refresh, is the page render asking for a new render-token secret, held by 10 per app per client IP and 60 per app across every address in a 60 second window, and observed/allowed name whichever of those two refused. An edits_too_large rejection carries the numeric cap that was exceeded instead of a name.

rungstring

On an app_busy refusal, how hard the app's own refusal ladder is refusing: throttled is the plain ceiling breach above; parked means a caller kept calling inside a wait it was given, so the server mints its own Retry-After (doubling from 60s to a 300s cap) and refuses until a quiet window passes even once the ceiling clears; closed is the same, plus the response closes the connection. Absent on every other kind.

Allowed:throttledparkedclosed
maxinteger

On a *_limit_exceeded refusal, that limit's number on the caller's plan.

min 0
featurestring

On a plan_required refusal, the capability the plan does not include. Never paired with limit / max.

Allowed:custom_domainwatermark_removalteams
upgradeUrlstring<uri>

Absolute link to the owner's own billing page, where the refusal is lifted — the team's page for a team-owned app. Omitted only when the owner has no handle and therefore no settings page of their own, so treat it as optional and fall back to your own copy. MCP appends it as an Upgrade: <url> last line; the CLI prints it under the message.

missingLevelsstring[]

On a connector_not_granted refusal, the access levels (in the order read, write, delete) the App's declared tools for the service need and the caller has not approved. Present only when approving would add something: call charming.connect(service) then. Absent means approving again would not help. On a refused PATCH /api/v1/apps/{appId}/connectors/{service}, the shared levels the holder's approval lacks instead.

recoveryRecoveryPair | RecoveryRetry | RecoveryShrink | RecoveryRefetch | RecoveryFixRouteLabel | RecoveryRename | RecoveryMigrateContract

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 revision_mismatch / invalid_if_match / 428 precondition_required, fix_route_label for 403 forbidden_write, rename for 409 manifest_id_immutable / manifest_id_conflict, and migrate_contract for 422 contract_migration_required. 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.

RecoveryRename
kindstringrequired
Allowed:rename
instructionsstringrequired
RecoveryMigrateContract
kindstringrequired
Allowed:migrate_contract
instructionsstringrequired
401

User authentication required.

okbooleanrequired
Allowed:false
errorobjectrequired
Show properties
kindstringrequired

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

Allowed:not_foundunknown_operationoperation_not_foundmethod_not_allowedoperation_failedtimeoutapp_busyvisitor_rate_limitedservice_busyunauthorizedsign_in_requiredtoken_expiredforbiddenaccount_not_joinedstaff_onlytwo_factor_requiredreauthentication_requiredforbidden_writeview_as_read_onlyemail_not_verifiedemail_needs_sign_instored_value_too_largestorage_fulltoo_many_keysstorage_method_unavailableinvalid_moduleinvalid_uiinvalid_filesbearer_requiredunpinned_cdn_scriptinvalid_route_schemainvalid_routes_shapecontract_migration_requiredinvalid_manifest_schemainvalid_manifest_exportsinvalid_requestinvalid_inputinvalid_outputunexpected_keyscapability_deniedcapability_errorexecutor_errorinvalid_call_shapealready_claimedmanifest_not_foundpayload_too_largemodule_too_largeui_too_largestyles_too_largedescription_too_longmissing_descriptioninvalid_descriptionrate_limitedimage_origin_deniedtoo_many_requestsexpiredalready_approvedanon_not_remixabletemplate_listing_incompletetemplate_media_invalidtemplate_listing_too_largeforbidden_template_editinvalid_if_matchprecondition_requiredexpected_revision_requiredidempotency_key_requiredidempotency_conflictapp_build_capacityapp_build_failedapp_build_expiredapp_build_authority_lostapp_build_unavailableapp_build_unsupportedversion_history_unavailableversion_not_restorablerevision_mismatchinvalid_revisioncandidate_effects_unsupportedold_string_not_foundold_string_not_uniqueinvalid_bucketbucket_unsetempty_editsedits_too_largemanifest_id_conflictmanifest_id_immutabletext_too_largestructured_data_too_largeapp_not_foundfeedback_not_foundfeedback_has_no_reply_recipientasset_too_largeasset_count_exceededasset_quota_exceededasset_invalid_keyasset_invalid_content_typeasset_errorinvalid_idsse_cookie_expiredinvalid_secret_namesecret_too_largesecret_already_existssecret_not_foundinvalid_iconteam_slug_takenalready_membertwo_factor_requiredrecent_login_requiredgrantee_not_foundinvite_cap_reachedinvite_sender_blockedrole_above_owninvite_delegation_owner_onlynot_your_inviteread_onlyhandle_takeninvalid_handlename_takeninvalid_domaindomain_takendomain_existsdomain_provider_unavailableapp_unclaimedlink_cap_reachedgrantee_is_ownergrantee_is_selfgrantee_already_has_accessalready_invitedroutine_limit_exceededinvalid_intervalop_requires_inputduplicate_routinewebhook_limit_exceededduplicate_webhookwebhook_disabledversion_limit_exceededplan_requiredconnector_call_limit_exceededconnector_rate_limitedconnector_not_grantedconnector_action_not_declaredconnector_no_personconnector_reconnect_requiredconnector_unavailableconnector_tool_failedconnector_cross_siteconnector_blocked_by_teamconnector_route_not_declaredconnector_function_not_approvedconnector_version_retiredconnector_holder_onlystorage_limit_exceededcopy_data_forbiddencopy_data_too_large
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 chrm_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
planstring

Present on every plan refusal: the tier the caller was refused under. Its presence is what marks an error as a plan refusal rather than a validation or permission failure.

Allowed:freeprobusinessenterprise
limitstring | integer

Which ceiling the call met, keyed by kind. A plan refusal (*_limit_exceeded) names the countable that ran out — version_history, routines_per_app, routines_per_owner, webhooks_per_app, webhooks_per_owner, connector_calls_per_month — and pairs it with max. An app_busy refusal names the bound it met and pairs it with observed and allowed; no plan lifts any of them. Two are per-app run bounds, concurrent_runs and runs_per_window; the third, render_token_refresh, is the page render asking for a new render-token secret, held by 10 per app per client IP and 60 per app across every address in a 60 second window, and observed/allowed name whichever of those two refused. An edits_too_large rejection carries the numeric cap that was exceeded instead of a name.

rungstring

On an app_busy refusal, how hard the app's own refusal ladder is refusing: throttled is the plain ceiling breach above; parked means a caller kept calling inside a wait it was given, so the server mints its own Retry-After (doubling from 60s to a 300s cap) and refuses until a quiet window passes even once the ceiling clears; closed is the same, plus the response closes the connection. Absent on every other kind.

Allowed:throttledparkedclosed
maxinteger

On a *_limit_exceeded refusal, that limit's number on the caller's plan.

min 0
featurestring

On a plan_required refusal, the capability the plan does not include. Never paired with limit / max.

Allowed:custom_domainwatermark_removalteams
upgradeUrlstring<uri>

Absolute link to the owner's own billing page, where the refusal is lifted — the team's page for a team-owned app. Omitted only when the owner has no handle and therefore no settings page of their own, so treat it as optional and fall back to your own copy. MCP appends it as an Upgrade: <url> last line; the CLI prints it under the message.

missingLevelsstring[]

On a connector_not_granted refusal, the access levels (in the order read, write, delete) the App's declared tools for the service need and the caller has not approved. Present only when approving would add something: call charming.connect(service) then. Absent means approving again would not help. On a refused PATCH /api/v1/apps/{appId}/connectors/{service}, the shared levels the holder's approval lacks instead.

recoveryRecoveryPair | RecoveryRetry | RecoveryShrink | RecoveryRefetch | RecoveryFixRouteLabel | RecoveryRename | RecoveryMigrateContract

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 revision_mismatch / invalid_if_match / 428 precondition_required, fix_route_label for 403 forbidden_write, rename for 409 manifest_id_immutable / manifest_id_conflict, and migrate_contract for 422 contract_migration_required. 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.

RecoveryRename
kindstringrequired
Allowed:rename
instructionsstringrequired
RecoveryMigrateContract
kindstringrequired
Allowed:migrate_contract
instructionsstringrequired
404

Build not found or inaccessible.

okbooleanrequired
Allowed:false
errorobjectrequired
Show properties
kindstringrequired

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

Allowed:not_foundunknown_operationoperation_not_foundmethod_not_allowedoperation_failedtimeoutapp_busyvisitor_rate_limitedservice_busyunauthorizedsign_in_requiredtoken_expiredforbiddenaccount_not_joinedstaff_onlytwo_factor_requiredreauthentication_requiredforbidden_writeview_as_read_onlyemail_not_verifiedemail_needs_sign_instored_value_too_largestorage_fulltoo_many_keysstorage_method_unavailableinvalid_moduleinvalid_uiinvalid_filesbearer_requiredunpinned_cdn_scriptinvalid_route_schemainvalid_routes_shapecontract_migration_requiredinvalid_manifest_schemainvalid_manifest_exportsinvalid_requestinvalid_inputinvalid_outputunexpected_keyscapability_deniedcapability_errorexecutor_errorinvalid_call_shapealready_claimedmanifest_not_foundpayload_too_largemodule_too_largeui_too_largestyles_too_largedescription_too_longmissing_descriptioninvalid_descriptionrate_limitedimage_origin_deniedtoo_many_requestsexpiredalready_approvedanon_not_remixabletemplate_listing_incompletetemplate_media_invalidtemplate_listing_too_largeforbidden_template_editinvalid_if_matchprecondition_requiredexpected_revision_requiredidempotency_key_requiredidempotency_conflictapp_build_capacityapp_build_failedapp_build_expiredapp_build_authority_lostapp_build_unavailableapp_build_unsupportedversion_history_unavailableversion_not_restorablerevision_mismatchinvalid_revisioncandidate_effects_unsupportedold_string_not_foundold_string_not_uniqueinvalid_bucketbucket_unsetempty_editsedits_too_largemanifest_id_conflictmanifest_id_immutabletext_too_largestructured_data_too_largeapp_not_foundfeedback_not_foundfeedback_has_no_reply_recipientasset_too_largeasset_count_exceededasset_quota_exceededasset_invalid_keyasset_invalid_content_typeasset_errorinvalid_idsse_cookie_expiredinvalid_secret_namesecret_too_largesecret_already_existssecret_not_foundinvalid_iconteam_slug_takenalready_membertwo_factor_requiredrecent_login_requiredgrantee_not_foundinvite_cap_reachedinvite_sender_blockedrole_above_owninvite_delegation_owner_onlynot_your_inviteread_onlyhandle_takeninvalid_handlename_takeninvalid_domaindomain_takendomain_existsdomain_provider_unavailableapp_unclaimedlink_cap_reachedgrantee_is_ownergrantee_is_selfgrantee_already_has_accessalready_invitedroutine_limit_exceededinvalid_intervalop_requires_inputduplicate_routinewebhook_limit_exceededduplicate_webhookwebhook_disabledversion_limit_exceededplan_requiredconnector_call_limit_exceededconnector_rate_limitedconnector_not_grantedconnector_action_not_declaredconnector_no_personconnector_reconnect_requiredconnector_unavailableconnector_tool_failedconnector_cross_siteconnector_blocked_by_teamconnector_route_not_declaredconnector_function_not_approvedconnector_version_retiredconnector_holder_onlystorage_limit_exceededcopy_data_forbiddencopy_data_too_large
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 chrm_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
planstring

Present on every plan refusal: the tier the caller was refused under. Its presence is what marks an error as a plan refusal rather than a validation or permission failure.

Allowed:freeprobusinessenterprise
limitstring | integer

Which ceiling the call met, keyed by kind. A plan refusal (*_limit_exceeded) names the countable that ran out — version_history, routines_per_app, routines_per_owner, webhooks_per_app, webhooks_per_owner, connector_calls_per_month — and pairs it with max. An app_busy refusal names the bound it met and pairs it with observed and allowed; no plan lifts any of them. Two are per-app run bounds, concurrent_runs and runs_per_window; the third, render_token_refresh, is the page render asking for a new render-token secret, held by 10 per app per client IP and 60 per app across every address in a 60 second window, and observed/allowed name whichever of those two refused. An edits_too_large rejection carries the numeric cap that was exceeded instead of a name.

rungstring

On an app_busy refusal, how hard the app's own refusal ladder is refusing: throttled is the plain ceiling breach above; parked means a caller kept calling inside a wait it was given, so the server mints its own Retry-After (doubling from 60s to a 300s cap) and refuses until a quiet window passes even once the ceiling clears; closed is the same, plus the response closes the connection. Absent on every other kind.

Allowed:throttledparkedclosed
maxinteger

On a *_limit_exceeded refusal, that limit's number on the caller's plan.

min 0
featurestring

On a plan_required refusal, the capability the plan does not include. Never paired with limit / max.

Allowed:custom_domainwatermark_removalteams
upgradeUrlstring<uri>

Absolute link to the owner's own billing page, where the refusal is lifted — the team's page for a team-owned app. Omitted only when the owner has no handle and therefore no settings page of their own, so treat it as optional and fall back to your own copy. MCP appends it as an Upgrade: <url> last line; the CLI prints it under the message.

missingLevelsstring[]

On a connector_not_granted refusal, the access levels (in the order read, write, delete) the App's declared tools for the service need and the caller has not approved. Present only when approving would add something: call charming.connect(service) then. Absent means approving again would not help. On a refused PATCH /api/v1/apps/{appId}/connectors/{service}, the shared levels the holder's approval lacks instead.

recoveryRecoveryPair | RecoveryRetry | RecoveryShrink | RecoveryRefetch | RecoveryFixRouteLabel | RecoveryRename | RecoveryMigrateContract

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 revision_mismatch / invalid_if_match / 428 precondition_required, fix_route_label for 403 forbidden_write, rename for 409 manifest_id_immutable / manifest_id_conflict, and migrate_contract for 422 contract_migration_required. 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.

RecoveryRename
kindstringrequired
Allowed:rename
instructionsstringrequired
RecoveryMigrateContract
kindstringrequired
Allowed:migrate_contract
instructionsstringrequired
Try it
Server
Authorization
Parameters
Request
curl -X GET 'https://charm.ing/api/v1/app-builds/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'
Response
{
  "ok": true,
  "buildId": "string",
  "intent": "create",
  "state": "queued",
  "sourceEtag": "string",
  "statusUrl": "http://example.com",
  "retryAfterSeconds": 0,
  "appId": "28c365d5-df94-4a54-8217-3ce51d068868",
  "revision": 1,
  "desiredRevision": 0,
  "activeRevision": 0,
  "url": "http://example.com",
  "attempts": 0,
  "acceptedAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "finishedAt": "2019-08-24T14:15:22Z",
  "elapsedMs": 0,
  "lockState": "locked",
  "inputDigest": "string",
  "lockDigest": "string",
  "resolvedDependencies": {
    "property1": "string",
    "property2": "string"
  },
  "queueDeadline": "2019-08-24T14:15:22Z",
  "deadline": "2019-08-24T14:15:22Z",
  "inspectionExpiresAt": "2019-08-24T14:15:22Z",
  "idempotencyExpiresAt": "2019-08-24T14:15:22Z",
  "source": {
    "files": {
      "property1": "string",
      "property2": "string"
    }
  },
  "error": {
    "kind": "string",
    "message": "string",
    "retryable": true,
    "details": {
      "execution": "not_started",
      "operationId": "string",
      "reservationId": "string"
    },
    "stage": "source",
    "target": "string",
    "specifier": "string",
    "path": "string",
    "line": 0,
    "column": 0
  }
}

Was this page helpful?