Compute
Work API reference
The five Compute work operations — quote, run, batch, status and result — with the authority each needs, what it returns, how replay behaves, and where exact paths are published.
The five work operations
Five operations carry paid work: quote, run, batch, status and result. Each answers inside a ComputeAPIResponseEnvelopeV1.
| Operation | What it does | What it returns |
|---|---|---|
| quote | Prices a described request | A signed quote with non_authorizing = true and an expiry |
| run | Submits one job for admission | The job identity and its admitted state |
| batch | Submits many items as one job | The job identity and the accepted item count |
| status | Reads current job and stage state | Typed states, and a next action on any non-success |
| result | Reads the finished result bundle | The bundle files, ending with result-manifest.json |
The envelope carries request_id, the operation, the contract release, a typed state, an evidence class, observed_at, valid_until and a structured next action. Read the typed state, not the prose.
Five agent tools are not five endpoints
The same five operations reach an AI agent as exactly five tools: lithi.quote, lithi.run, lithi.batch, lithi.status and lithi.result. lithi.plan() and lithi.recommend() are local helpers. They neither quote, admit nor run paid work.
The REST surface is wider than that tool list. It also carries artifact upload authorization, artifact verification, cancellation and result part retrieval. Do not infer the endpoint list from the tool list.
What authority each operation needs
Every work operation authenticates with a bounded work key. A key is personal, service or automation, and it holds six work scopes.
Management scopes are never mintable on a work key. No work key can register a destination, change spend or mint an identity. Finance, destination and identity administration stay separate from work submission.
A quote never authorizes work. Approval is a separate act, and run and batch admit work only when the required approval is already in place.
Replay behavior
Every effect has a unique idempotency tuple and a payload digest. An exact replay returns the prior result. The same identity with a different digest is equivocation, and the operation refuses.
Idempotency is scoped separately for a request, a batch, a manifest, a logical item, an artifact and a destination write. A late or stale attempt, lease, version or epoch cannot advance state.
The response tells you whether you received a replay or new work. Read that field rather than assuming a key lifetime.
Artifacts and cancellation
An artifact moves through a fixed sequence: PLANNED, UPLOAD_AUTHORIZED, UPLOADING, UPLOADED_UNVERIFIED, VERIFIED, then ACCEPTED, REJECTED or ORPHAN_QUARANTINED, then DELIVERABLE, EXPIRED, DELETING and DELETED.
Cancellation is a request, not an instant. A job enters CANCELLING and reaches CANCELLED only once running stages have stopped. Work accepted before cancellation still appears in the bundle, and the applicable commercial policy states what is charged for it.
Terminal states and replanning
A job ends in SUCCEEDED, PARTIAL, FAILED or CANCELLED. AWAITING_REVIEW is not terminal; a person still has to decide.
On SUCCEEDED or PARTIAL, download the bundle and check result-manifest.json. It is written last and is the only complete-bundle marker. On FAILED or CANCELLED, read the next action on the status response before resubmitting.
Admission returns REPLAN_REQUIRED when the priced request no longer matches what you sent. Quote again, then resubmit. The applicable commercial policy states what a refused admission costs.
Where the exact paths are published
Your base URL, the current API version and your key's scopes appear in developer settings in the portal. Every path, request schema, response schema and per-operation error schema is generated into the API description you download there.
There is no single global error table. Read the error schema for the operation you called, and see what each state value means before writing retry logic.