# Orchestrator API (DOCS-ORCH-33-001)

> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

Last updated: 2025-11-25

## Scope & headers
- Base path: `/api/v1/orchestrator`.
- Required headers: `Authorization: Bearer <token>`, `X-Stella-Tenant`, `traceparent` (recommended), `Idempotency-Key` for POSTs that mutate state.
- Error envelope: see `docs/api/overview.md` (code/message/trace_id).

## DAG management
- `POST /dags` — create/publish DAG version. Body includes `dagId`, `version`, `steps[]`, `edges[]`, `metadata`, `signature`.
- `GET /dags` — list DAGs (stable sort by `dagId`, then `version` DESC). Filters: `dagId`, `active=true|false`.
- `GET /dags/{dagId}/{version}` — fetch DAG definition.
- `POST /dags/{dagId}/{version}:disable` — disable a version (requires `orchestrator:admin`).

## Runs
- `POST /runs` — start a run; accepts `dagId`, optional `version`, `inputs` (object), `runToken` (idempotency). Returns `runId`, `traceId`.
- `GET /runs` — list runs with filters `dagId`, `status`, `from`, `to`. Sort: `startedUtc` DESC, then `runId`.
- `GET /runs/{runId}` — run detail with step states and hashes.
- `POST /runs/{runId}:cancel` — request cancellation (best-effort, idempotent).

## Steps & artifacts
- `GET /runs/{runId}/steps` — list step executions.
- `GET /runs/{runId}/steps/{stepId}` — step detail, including `attempts[]`, `logsRef`, `outputsHash`.
- `GET /artifacts/{hash}` — retrieve artifact by content hash (if tenant owns it).

## WebSocket stream
- `GET /runs/stream?dagId=&status=` — server sends NDJSON events: `run.started`, `run.updated`, `step.updated`, `run.completed`, `run.failed`, `run.cancelled`. Fields: `tenant`, `dagId`, `runId`, `status`, `timestamp`, `traceId`.

## Admin/ops
- `POST /admin/warm` — warm caches for DAGs/plugins (optional).
- `GET /admin/health` — liveness/readiness; includes queue depth per tenant.
- `GET /admin/metrics` — Prometheus scrape endpoint.

## Determinism & offline posture
- All list endpoints have deterministic ordering; pagination via `page_token`/`page_size`.
- No remote fetches; DAGs/plugins must be preloaded. Exports available as NDJSON with stable ordering.
- Hashes lowercase hex; timestamps UTC ISO-8601.

## Security
- Scopes: `orchestrator:read`, `orchestrator:write`, `orchestrator:admin` (publish/disable DAGs, cache warm).
- Tenant isolation enforced on every path; cross-tenant access forbidden.