Run a workflow. Keep the receipt.
Esy executes declared workflows and returns durable artifacts — with the provenance, the quality checks, and the itemised cost that produced them. These docs are written for someone with an API key and a terminal.
Three pages, in this order.
Make something work first, then understand why it worked, then look up the details. About five minutes each.
Quickstart
Four curl commands from an empty shell to a finished image. Real requests, real responses.
Read Start hereHow Esy works
The whole system on one page — the five nouns, what happens inside a run, and where cost is counted.
Read Start hereAPI conventions
Base URL, auth, casing, ids, pagination, idempotency. Everything true of every endpoint.
ReadThe nouns everything else is built from.
A workspace holds projects. A workflow is a versioned definition. A run is one execution of it, and an artifact is what it produced. Everything below is a detail of one of those.
Workflows
The versioned definition a run executes — intake, steps, bindings, gates, and declared output.
Read ConceptsIntake
The inputs a workflow accepts, and why they ask for outcomes rather than mechanisms.
Read ConceptsRuns and steps
Nine statuses, per-step telemetry, and how steps bind to models through roles.
Read ConceptsGates and review
Quality gates, the escalation ladder, the human review queue, and typed holds.
Read ConceptsArtifacts
What a run produced, with its QA record, cost ledger, and provenance back to the run.
Read ConceptsCosts and budgets
Three cost states, how spend rolls up, and how a budget refuses a run before it spends.
Read ConceptsVersioning
Immutable versions, a movable live pointer, and the frozen spec each run pins.
Read ConceptsGeneration Orders
One workflow fanned into N child runs with variation, dedupe keys, and a budget cap.
Read ConceptsSource policies
Which approved sources a subject may be researched from, what each covers, and where it stops.
Read ReferenceErrors
Every status code with the real response body, what causes it, and how to fix it.
Read ReferenceRun events (SSE)
Stream a run instead of polling it — snapshot on connect, then every transition.
Read ReferenceGlossary
Every term in a sentence, including the names the code uses when they differ.
ReadHow Esy thinks about producing output.
Structure over prompting
You pick a workflow and fill in its declared intake. There is no prompt box hoping for the right output.
Artifacts over conversations
Every output is persisted with its provenance, telemetry, and review state. Nothing that matters is ephemeral.
Gated, not hopeful
Work is judged before it reaches you, and a check only counts if something actually measured it.