Reference · API

API reference

Create workflow runs and read back artifacts, step telemetry, and cost ledger entries. Per-endpoint detail pages are generated from the OpenAPI schema once published.

Base URL

Production: https://api.esy.com

Runtime endpoints

POST/v1/runsCreate and execute a workflow run.

GET/v1/runsList persisted runs for the authenticated workspace.

GET/v1/runs/{runId}Fetch run details, step telemetry, and cost ledger entries.

GET/v1/artifactsList persisted artifacts.

GET/v1/artifacts/{artifactId}Fetch artifact content, metadata, and cost ledger entries.

Example response

POST /v1/runs · 201 createdjson

{
  "id": "run-a1b2c3d4",
  "status": "running",
  "templateId": "generate-clip-art-asset",
  "queuedAt": "2026-05-16T22:14:12.482Z",
  "startedAt": "2026-05-16T22:14:12.604Z"
}

Authentication

Requests are authenticated with a bearer token scoped to a workspace. External API keys, scopes, and rate limits will be documented here once they’re available. For now, manage workspaces and tokens from app.esy.com.

Versioning

All endpoints are versioned under /v1. Breaking changes will land on a new path (/v2) and be tracked in the changelog.