Products

List your own compile jobs

Your tenant's compile jobs, newest first. Source is never echoed back.

Parâmetros

Respostas

Submit your own Product Bundle to the Foundry

Compile and gate a validator **you** wrote, under your own tenant.

**202, not 201** — the job is accepted, not finished. Poll the companion `GET`.

The submission must carry an authorship `signature` over its `bundle_hash`, made with the key an operator enrolled for your tenant. That signature is what the Certified Product Artifact records as authorship, and it is deliberately a different fact from the API credential that sent the request: credentials rotate, and a certification has to keep answering *who wrote this validator* years later.

A submission that fails a static gate comes back **already REFUSED** and is never queued — the compile slot is the expensive thing, and source that cannot pass a lexer will not pass a compiler. The refusal names the offending rule in the gate report's own vocabulary.

⚠️ Compiling is not binding and certainly not certifying. A green report is evidence; `POST /v1/products/{product_id}` with this `compile_id` is what deploys it at DRAFT.

Corpo da requisição

FoundryCompileRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Read one of your compile jobs and its gate report

One compile job, at whatever stage it has reached.

The gate report lists **every** gate that ran, passes included, plus a `deferred` block naming what this stage deliberately did not prove. A report showing only failures could not answer "was this checked?", which is the question a countersigner asks.

⛔ Another tenant's `compile_id` and one that never existed are the same DynamoDB miss — the tenant is a partition-key segment, so 404-before-403 holds in its strongest form.

Parâmetros

Respostas

How much of your daily compile allowance is left

Used, allowed, and when the window rolls.

⚠️ This **raises rather than reporting zero** when the count cannot be taken. A quota surface answering *"0 of 25 used"* during an outage would be worse than no surface, because a caller would believe it.

⚠️ Its own path rather than `/v1/products/quota`, deliberately: FastAPI matches in declaration order and `/v1/products/{product_id}` is declared above, so `quota` would be captured as a product id and answered `PRODUCT_NOT_FOUND`.

Respostas

Your tenant's own OpenAPI document

Every action your certified products declare, as a typed API.

⭐ Derived from your manifests on every read, so binding, versioning or suspending a product changes the next response and nothing has to be regenerated. The document describes **your** products and no one else's — the tenant is a segment of the partition key, so another tenant's product is not filtered out here, it is unaddressable.

⛔ Every operation is a shipped generic route with its template filled in. The product id is in the path and the action is a path segment or a `const` in the body; nothing here is a route of its own.

⚠️ `servers` is absent by construction — this service sits behind a gateway and does not know its own public URL, and a caller-supplied one baked into a generated client would be a way to send credentials elsewhere. Use the host you fetched the document from.

Respostas

A generated client for your own products

A single-file client, generated from the document above.

⭐ The reason this is generated rather than left to a codegen tool is `wait_for_state`. Writes here are obligation-first, so an action your validator refuses answers 200 and is refused a beat later; a truthful client polls the instance read for the declared state **and** for `awaiting_index: false`. Dropping that second condition is a race, and no off-the-shelf generator emits it.

Stdlib only, so it runs where you paste it. `base_url` is a constructor argument and is never guessed, for the reason the document gives for omitting `servers`.

Parâmetros

Respostas

Bind a shipped template as your own DRAFT product

Draft-mode deploy: bind one of the shipped templates for your own tenant.

Bindable **only in a showcase sandbox estate** — faucet money, simulated rails, reset with notice — because a DRAFT artifact has passed no conformance run and no adversarial battery. A production binding is born CERTIFIED naming a certification produced elsewhere, and that is an operator call.

Idempotent on artifact identity: a repeat with a byte-identical manifest answers **200** with `bound: false` and appends no version.

⚠️ Two preconditions that are not about your manifest, both named in the refusal if you meet them: a tenant with no QBRL minting-policy binding cannot resolve its binding params, and a non-incumbent tenant cannot yet receive an inbound credit at all — so it can bind and plan its scenarios, and cannot fund an instance.

Parâmetros

Corpo da requisição

TenantDraftBindRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Run the adversarial battery against your own product

Attack your applied script with the generated battery, and report a card.

**202, not 201** — the engine is a bounded job, not a request. Poll the companion `GET`.

The battery evaluates your applied script's **UPLC** against contexts it assembles, fuel-bounded, in a networkless sandbox. It never submits a transaction: most of these attacks cannot be *built* by the platform's own interpreter, and of those that can, the ledger would refuse them before your script ran — so a live-head battery would go green having measured the chain rather than your Haskell.

⚠️ **Grey is not green.** A class whose positive control the script refused anyway proved nothing and is reported `inconclusive`, which a certification treats exactly as it treats a red.

⚠️ One at a time per product: a second run would spend a build slot answering a question already in flight, and two cards for one script make "which one did the certification reference" a guess.

Errors: 404: PRODUCT_NOT_FOUND (also for another tenant's) 409: BATTERY_ALREADY_RUNNING 422: PRODUCT_NOT_PLANNABLE, BATTERY_NOT_PLANNABLE, PRODUCT_NOT_PARAMETRIC 503: PRODUCT_ARTIFACT_UNAVAILABLE

Parâmetros

Respostas

Read a battery run and its report card

The run's status and, once `DONE`, where its signed card lives.

⚠️ `RUNNING` for longer than the engine's own ceiling means the task was lost — a background job does not survive a deploy — and starting a new one is then permitted. The row is not silently adopted.

Parâmetros

Respostas

Your product's certification, and whether it has gone stale

The signed certification for your own binding, its countersignature, staleness.

⭐ **Stale is reported, never enforced.** A battery upgrade does not invalidate a LIVE product: an inventory bump would otherwise be an estate-wide outage triggered by adding an attack class, and the products it would take down are exactly the ones that passed the previous inventory honestly.

⚠️ **A DRAFT product answers 404 `CERTIFICATION_NOT_FOUND`, and that is the expected state, not a fault.** Certification requires a conformance transcript, which needs a live head and a funded instance — and the estate stack that runs one does not exist yet, so a product you bind in the sandbox cannot be certified there today. The refusal says so.

Everything needed to verify the artifact offline is in the response, and the published public keys live beside it in the store. The referenced evidence is one hop away, at `…/certification/evidence/{kind}`.

Parâmetros

Respostas

Certify your own product from the evidence it produced

Assemble, sign and record the Certified Product Artifact for your binding.

⛔ **The body is empty and the evidence is looked up, not named.** An operator naming `{hash, key}` is naming documents it has read; a tenant naming them could name somebody else's, and the certification's integrity checks would not catch it — a valid document about another product is still a valid document. So this route finds what *your own* runs produced: the gate report from your compile (when the product came from one), the transcript from your sealed conformance run, and the card from your completed battery.

⚠️ **The battery card must describe your current applied script.** A card produced before a version bump attests to different bytes, so it reads as absent rather than as evidence — the conservative direction, and the same equality laas-86 puts at the LIVE gate.

This reaches **CERTIFIED**. It does not reach LIVE: that needs a human countersignature the platform cannot mint, produced under a role no task role can assume.

Errors: 404: PRODUCT_NOT_FOUND 409: CONFORMANCE_REQUIRED, BATTERY_REQUIRED, PRODUCT_NOT_CERTIFIABLE 422: CERTIFICATION_EVIDENCE_REFUSED (an evidence verdict is not `accepted`) 503: CERTIFICATION_POLICY_UNAVAILABLE, GOLDEN_VECTOR_CAPTURE_UNAVAILABLE

Parâmetros

Respostas

One evidence document a certification references

The gate report, the conformance transcript, the battery card, or the vectors.

A certification staples its evidence together **by reference**, because a hashed document cannot be rewritten and a battery card carries a whole transaction context per case. This is the dereference: the document at the key the signed body names, re-hashed against the hash the signed body names.

⛔ **Byte-exact, with nothing stripped.** Your recourse is to re-hash these bytes and compare, so a friendlier projection would break the only property that makes the evidence worth reading.

Each document carries its own claims and disclaims *inside* the hashed body — what it proves and what it explicitly does not. Read them: a renderer cannot omit what it does not control, and that is the point of them being there.

Parâmetros

Respostas

Open a conformance run against your own product

Derive the plan, resolve the roster, and open a run you drive step by step.

A conformance run is what turns a *declared* manifest into a *proved* one: every action it declares executed against the compiled script on a real head, with the schema IR round-tripping the datums the script accepted onto the chain.

**You supply only accounts you own.** The platform resolves their verification keys itself — no read publishes one, and a synthesised key produces an instance nobody can sign for — and it chooses every payload from the manifest, because an action driven with a value nobody chose proves nothing.

⚠️ An incomplete plan does **not** refuse here. An uncovered action, an unreached terminal state or a dead-end state each becomes a failed finding and a `refused` transcript, which is more useful than no document at all.

Errors: 403: DRAFT_RUN_NOT_AVAILABLE (a DRAFT product outside a sandbox estate) 404: PRODUCT_NOT_FOUND, ACCOUNT_NOT_FOUND (both also for another tenant's) 409: PRODUCT_NOT_RUNNABLE (SUSPENDED or RETIRED) 422: PRODUCT_NOT_PLANNABLE, ROSTER_TOO_SMALL, ROSTER_NOT_DISTINCT, ACCOUNT_NOT_USABLE 503: PRODUCT_ARTIFACT_UNAVAILABLE, ACCOUNT_KEY_UNAVAILABLE

Parâmetros

Corpo da requisição

ConformanceRunOpenRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Read a conformance run, its steps and its verdict

The run's plan with each step's recorded outcome merged in.

One read answers both *what is left* and *what happened*, because a client that has to join two lists will eventually join them wrong. The rules a truthful driver must honour travel in the response's own `driving` block.

⛔ Another tenant's `run_id` and one that never existed are the same 404 — the tenant is a partition-key segment.

Parâmetros

Respostas

Drive one step of a conformance run

Drive step `index`, then observe it from the head and record what happened.

The platform takes a UTxO snapshot before the step, drives it through the same generic write route you would call yourself, waits a bounded time for the chain's answer, snapshots again, and records the value deltas and the datum round-trip. **The observations are ours, taken from the head** — which is what makes a run you drive usable as evidence.

⛔ **A step is judged by `chain_outcome`, never by this call's status.** The write path is obligation-first: an action your validator refuses answers 200 and is refused a beat later.

Steps run **in order**, one per request, starting at the run's `next_step`. A retry of the same index is safe and replays: the step's own conditional write is the claim lock, and the idempotency key handed to the write is derived from (run, index).

The last step **seals** the run and publishes its transcript; the response carries the verdict.

Errors: 404: RUN_NOT_FOUND, STEP_NOT_FOUND 409: RUN_NOT_OPEN, STEP_OUT_OF_ORDER, SCENARIO_HAS_NO_INSTANCE 422: RUN_PRODUCT_MISMATCH 503: HEAD_SNAPSHOT_UNAVAILABLE, QBRL_POLICY_UNBOUND, TRANSCRIPT_STORE_UNAVAILABLE

Parâmetros

Corpo da requisição

ConformanceStepRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Create an instance of a tenant product

Parâmetros

Corpo da requisição

ProductInstanceCreateRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Drive a declared action on a product instance

Parâmetros

Corpo da requisição

ProductActionRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Close a product instance and release its value

Parâmetros

Corpo da requisição

ProductCloseRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

The scenarios this product's manifest declares

Every declared action and terminal state, as a runnable plan.

⭐ The plan is the one a conformance run derives — same pure function of the same manifest — with the exact generic-route request per step. Run them yourself: this route executes nothing.

⛔ **Assert the outcome, never the HTTP status.** The write path is obligation-first, so an action the script refuses answers 200 and is refused on chain a beat later. The rules a truthful runner has to honour are in `driving`, in the response, because that is where somebody writing one will read them.

⚠️ A step whose payload needs a real account's verification key comes back with `drivable: false` and `unsynthesizable` populated: no read publishes a key, so the platform cannot hand you one to send. The plan is still worth reading.

Parâmetros

Respostas