9f6e6f7fb3
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Signals CI & Image / signals-ci (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
45 lines
2.5 KiB
Markdown
45 lines
2.5 KiB
Markdown
# 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.
|