API Documentation

Interactive workflow orchestration reference with FSM & Zero-Trust Audit.

📄 OpenAPI 3.1 JSON

General Principles

This section describes the architectural rules and structures used throughout the Holarchy API. Understanding these principles ensures robust, production-grade integration.

Request Architecture (Headers vs Body)

Holarchy enforces a strict separation between Business Payloads and Orchestrator Metadata:

  • Request Body (input): 100% pure business data validated against the blueprint's start step contract.
  • Authorization: Bearer <token> or X-Client-Token: Client authentication.
  • X-Webhook-URL: Callback URL triggered upon job completion or failure.
  • X-Job-Timeout: Execution timeout in seconds.
  • X-Job-Priority: Queue priority (critical, high, normal, low).
  • X-Correlation-ID: End-to-end distributed tracing identifier.
  • Idempotency-Key: Prevents duplicate task executions on network retries.

Response Structure (5 Clean Storage Zones)

Job states are cleanly partitioned into five dedicated storage zones:

{
  "id": "job_01j7v66...",
  "blueprint": "order_flow",
  "status": "finished",
  "input": { "order_id": 42, "amount": 1500.0 },
  "output": { "receipt_id": "rcpt_77", "status": "paid" },
  "steps": { "init": { ... }, "charge": { ... } },
  "history": [ { "step": "init", "duration_ms": 14, "timestamp": 1718000000.124 } ],
  "params": { "env": "production" },
  "meta": { "priority": "high", "timeout": 120 }
}