stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/orchestrator/api.md
StellaOps Bot 9f6e6f7fb3
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Signals CI & Image / signals-ci (push) Has been cancelled
Details
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Details
Policy Simulation / policy-simulate (push) Has been cancelled
Details
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Details
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Details
devportal-offline / build-offline (push) Has been cancelled
Details
up
2025-11-25 22:09:44 +02:00

2.5 KiB
Raw Permalink Blame History

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.