# AI Execute endpoint and recovery guide

Public documentation revision 3 · October 7, 2026
Applies to Managed API 0.1.0rc3. The original OpenAPI contract is unchanged.

All protected routes use a provisioned bearer key. Tenant and delegated
customer come from the live key, not request fields. POST requires JSON, an exact
schema, Content-Length and at most 16 KiB; duplicate JSON keys are refused.
The versioned OpenAPI defines the exact request and response schemas.

| Route | Authority / effect |
| --- | --- |
| POST `/v1/businesses` | Admin + authenticated source approval; cumulative budget |
| GET `/v1/businesses/{id}` | Authorized business/customer read |
| POST `/v1/businesses/{id}/aliases` | Admin; register an unfunded business reference |
| POST `/v1/business-executions` | Execute/admin; request a job within the approved budget |
| GET `/v1/executions/lookup?scope_id=...&operation_key=...` | Business or registered alias; original attempt lookup |
| GET `/v1/executions/{id}` | Authorized historical state |
| POST `/v1/executions/{id}/recover` | Empty object; read-only provider recovery, no new job |
| POST `/v1/executions/{id}/resume` | Empty object; HELD/PREPARED only, fresh checks |
| POST `/v1/executions/{id}/cancel` | Empty object; execute/admin; no exposed-cost refund |
| GET `/v1/executions/{id}/receipt` | Unsigned historical digest; never dispatch permission |
| GET `/v1/scopes/{id}` | Customer-authorized business balance |
| POST `/v1/executions` | Legacy regression only; disabled in CLI |
| `/v1/billing/*` | Admin; separate Stripe test contract |

## Create and inspect

Send `business_id`, `attempt_key`, `connection_id`, `action`, `parameters` and
`max_cost_micro`. Optional `scope_alias` must already refer to that business.
The provider contract determines the required maximum reservation. Keep the
business ID, attempt key and exact request before execution. An identical
request reads the existing execution, including after subscription expiry or
connection retirement; changing its economic content conflicts.

An HTTP success may return HOLD. Read the decision and execution state.
A held job requires explicit resume when budget is available and fresh checks
pass. Expired or revoked approvals block new financial work while original
inspection and recovery remain available. They never erase existing exposure.

## Recover the original

After a lost gateway reply, look up the same business ID and attempt key.
A 404 does not prove the provider job was never sent. Retain the identity and
repeat only the identical gateway request if needed. Do not change providers,
change the key or send a provider POST directly to escape uncertainty.

Recovery refers to the original execution and cannot dispatch a successor.
UNKNOWN, SUBMITTED and COST_PENDING never resume a financial POST. Empty,
incomplete, ambiguous or conflicting evidence keeps exposure reserved.
Verified final-cost evidence settles once; repeated recovery creates no credit.
An evidence conflict, changed final cost or above-ceiling charge requires
operator review and does not clear automatically. Supply neither a guessed
provider ID nor a customer-calculated cost as proof of finality.

Cancellation releases only work that has not been dispatched. Exposed work
remains reserved until authoritative final cost. A held successor requires
explicit resume and fresh authorization, approval, provider and capacity checks.

## Scope and support

The implemented provider contract is a separate-process loopback fixture only.
Its final-cost evidence is synthetic. Native cost ceilings, original-job recovery
and irreversible billing finality remain unqualified. Completion, price
estimates, empty lookup and cancellation alone do not establish a final bill.

Integrity or recovery failures require the evaluation operator. They never
authorize reset or resend. Keep the original request, execution reference and
sanitized error for that review; keep credentials and raw records private.
Detailed operator procedures accompany the evaluator under agreed review scope.

This is one-host local evaluation. Backup restoration, joint-history rollback,
host migration and automatic history migration are not qualified. Existing RC2
databases are refused. Preserve historical consumption and unresolved work
through a separately reviewed cutover. No native provider or independently
operated production recovery is qualified. Production is NO_GO; no paid hosted
endpoint or availability SLA is offered.