API reference · Workflows

Workflows and catalog

Find a workflow to run and read its contract. Concepts live on Workflows; this page is the endpoint list.

GET/v1/catalog/workflowsPublic catalog. No key.
GET/v1/catalog/workflows/{workflow_id}Public contract. No key.
GET/v1/workflowsWorkflows visible to you, including internal ones.
GET/v1/workflows/{workflow_id}One workflow, unredacted where you have access.
GET/v1/workflows/{workflow_id}/versionsIts immutable versions.
POST/v1/workflows/dry-runResolve a draft definition without spending.
POST/v1/workflows/estimatePrice a draft definition.
GET/v1/modelsThe model registry.
GET/v1/toolsThe tool registry.

GET /v1/catalog/workflows

Every public workflow, summarised. Unauthenticated.

requestbash
curl -s https://api.esy.com/v1/catalog/workflows
one itemjson
{
  "id": "generate-coloring-page",
  "name": "Generate Coloring Page",
  "shortDescription": "Printable line-art coloring page, post-processed, gated, classified.",
  "artifactClass": "visual",
  "depth": "quick",
  "estimatedRuntime": "30-90 sec",
  "includesQa": true,
  "stages": [ { "name": "Render", "description": "…", "stepCount": 1 }, … ],
  "whatYouProvide": [ … ],
  "whatYouGet": [ … ],
  "qaChecks": [ … ],
  "version": "2026.09.10"
}

The response is { items, total }. Because it needs no key, it is safe to call from a build step — this site’s own workflow pages are generated from it.

GET /v1/catalog/workflows/{workflow_id}

The full contract for one public workflow. Unauthenticated.

Returns intakeSchema, runtimeSteps, gates, artifactSchema, and version history. Prompt templates, provider bindings, and budgetPolicy come back as "redacted". Read intakeSchema here before you build an intake.

GET /v1/workflows

Workflows you can see, including internal ones.

FieldTypeRequiredDescription
visibilityenumoptionaldraft, internal, public.
includeDeprecatedbooleanoptionalDeprecated workflows are hidden by default.
offset / limitintegeroptionalPagination.

GET /v1/workflows/{workflow_id}/versions

The append-only version history.

See Versioning for how versions, revisions, and the live pointer relate.

POST /v1/workflows/dry-run

Resolve and price a draft workflow definition without calling a provider.

Takes a definition, not a templateId
Send intakeSchema, runtimeSteps, providers, and a sample intake. A templateId is ignored, and the response will say ok: true with zero steps. Full example on Workflows.

POST /v1/workflows/estimate

Price a draft runtimeSteps + providers pair.

Optional thresholdUsd flags the definition as high-cost when the typical estimate exceeds it.

GET /v1/models

The model registry — every id a provider binding may name.

requestbash
curl -s "https://api.esy.com/v1/models?capability=image" \
  -H "Authorization: Bearer $ESY_API_KEY"

Filter with capability = text, image, video, or tool. Each entry carries pricing and capability flags such as supportsNativeTransparency — the facts the engine reads to pick a mechanism. Use these ids in a run’s providers override.

GET /v1/tools

The tool registry — non-model steps such as esy/chroma-key.

Tools are bound to roles exactly like models are.