# Orchestrator API

Scope and headers
- Base path: /api/v1/orchestrator.
- Headers: Authorization Bearer token, X-Stella-Tenant, Idempotency-Key for POSTs.
- traceparent is recommended for tracing.
- Error envelope follows api/overview.md.

DAG management
- POST /dags: create or publish a DAG version with steps, edges, metadata, signature.
- GET /dags: list DAGs sorted by dagId then version desc; filter by dagId or active.
- GET /dags/{dagId}/{version}: fetch DAG definition.
- POST /dags/{dagId}/{version}:disable: disable a version (admin scope).

Runs
- POST /runs: start a run with dagId, optional version, inputs, and runToken.
- GET /runs: list runs with filters for dagId, status, from, to; sorted by startedUtc desc.
- GET /runs/{runId}: run details with step hashes and status.
- POST /runs/{runId}:cancel: request cancellation (best-effort).

Steps and artifacts
- GET /runs/{runId}/steps: list step executions.
- GET /runs/{runId}/steps/{stepId}: step details with attempts and outputs hash.
- GET /artifacts/{hash}: retrieve content-addressed artifacts owned by the tenant.

WebSocket stream
- GET /runs/stream?dagId=&status=: NDJSON events for run and step updates.
- Event types: run.started, run.updated, step.updated, run.completed, run.failed, run.cancelled.

Admin and ops
- POST /admin/warm: warm caches for DAGs and plugins.
- GET /admin/health: readiness with queue depth by tenant.
- GET /admin/metrics: Prometheus scrape endpoint.

Determinism and offline
- List endpoints return deterministic ordering; pagination uses page_token and page_size.
- Hashes are lower-case hex; timestamps UTC ISO-8601.
- No remote fetches; DAGs and plugins are preloaded in offline bundles.

Security
- Scopes: orchestrator:read, orchestrator:write, orchestrator:admin.
- Tenant isolation enforced on every endpoint.