Get started · Mental model

How Esy works

Esy runs a declared workflow and keeps the receipt. Five nouns carry the whole system, and once you can name them the API stops being surprising. This page is the map; every box on it links to the page that goes deeper.

The five nouns

Everything in the API is one of these, in this order. A workspace holds projects; a workflow is a reusable definition; a run is one execution of it; an artifact is what the run produced.

WORKSPACE → PROJECT → WORKFLOW → RUN → ARTIFACTWorkspaceorganization | personal/v1/workspacesProjectkind: general | brand…/projectsWorkflowversioned template/v1/workflowsRunone execution/v1/runsArtifactoutput + provenance/v1/artifacts
The object modelThe API path under each box is where that object lives. Note the first one: the API says workspace, and a workspace has a kind of either organization or personal.
NounWhat it isWhere it lives
WorkspaceThe billing and membership boundary. Yours is created for you at signup./v1/workspaces
ProjectAn optional grouping inside a workspace, so runs and costs roll up somewhere meaningful.…/projects
WorkflowThe versioned definition: what inputs it takes, what steps it runs, which models, which gates, what it outputs./v1/workflows
RunOne execution, with per-step telemetry and cost. Immutable once terminal./v1/runs
ArtifactWhat the run produced, plus the QA record and the cost ledger that made it./v1/artifacts
Organization or workspace?
You will see both words. The concept is a workspace, and that is what the API calls it; an “organization” is a workspace whose kind is organization (the other kind is personal). These docs say workspace throughout.

What happens inside a run

A workflow is not a prompt. It is a short program: an ordered list of steps, each bound to a model or a tool, with gates between them that decide whether the next step is allowed to start.

5 STEPS · 3 GATESimageRenderstep-1imageGeneratorg1toolPost-processstep-2seal gapstoolAuditstep-3stroke, marging2llmText gatestep-3btextGate · OCRg3llmClassifystep-4classifiereach step names a ROLE; the workflow binds that role to a model in the registry
generate-coloring-page, as actually declaredA gate does not run anything. It judges what the previous step produced and declares which step id it unlocks. Steps do; gates judge.

Steps come in kinds — image, llm, tool, subWorkflow, agent, code — and each names a role rather than a model. The workflow binds roles to concrete models, which is why you can swap the image model without editing a single step. Runs and steps has the detail.

The lifecycle you will actually see

Nine statuses, not five. Most runs go pending → queued → running → completed, but a workflow that declares an approval gate parks its run in review until a human decides.

RUN STATUSno approval gate declaredpendingplannedorder childrenqueuedrunningfailedcancelledgatereviewapprovecompletedrejectedchanges_requestedstop polling on: completed · review · failed · cancelled · rejected · changes_requested
Run status transitionsThe three statuses on the right only exist for workflows with an approval gate. For everything else, running goes straight to completed.

Ask for outcomes, not mechanisms

This is the one design rule that explains most of the intake schemas you will meet. Every run answers two questions, and they belong to different layers.

1 · THE INTAKE ASKS2 · THE ENGINE DECIDESWhat do you want?prompt“a fox in a waistcoat”background“see-through”aspectRatio1:1a promise. still true in five years.How should we make it?model registrysupports_native_transparencytruefalserender transparentremoval skipped · $0render, then key outesy/chroma-keyBoth record transparencyMechanism in provenance.a mechanism-judged pipeline can never be improved — so QA judges the result
Intake speaks outcomes, bindings speak mechanismsYou say what you want. The engine reads the bound model’s capability flags and decides how. The mechanism it chose is recorded in provenance, and QA judges the outcome — never the mechanism.

The practical consequence: an intake field asks for a result you would still want in a year, never for an implementation you happen to know about today. See Intake.

Where the money is counted

Cost is recorded per provider call, not per run, and each entry moves through three states. There is no fourth state.

PROVIDER_COST_LEDGERestimatedbefore the callprovider_reportedafter the callreconciledagainst the invoicethree states — roll up: step → run → workflow → project → workspace
Cost statesBudgets are enforced before a run starts, using the estimate. A refused run costs nothing and is still recorded. See Costs and budgets.

What Esy is not

Esy runs workflows and preserves how their outputs were made. It does not optimise what happens to an artifact afterwards — sales, clicks, engagement — and it does not replace the judgement about what is worth making. If you are looking for a chat API, this is the wrong system: Esy is artifact-first, and a conversation is at most an input.

In short
  • Workspace → project → workflow → run → artifact. Every endpoint hangs off one of those five.
  • A workflow is a program with gates, not a prompt. Steps name roles; the workflow binds roles to models.
  • Intake asks for outcomes. The engine picks the mechanism from model capabilities and records which one it used.
  • Cost is per provider call, in three states, enforced against budgets before the run starts.