Orchestrations API

GET /api/v1/orchestrations

List all configured orchestrations.

curl http://localhost:8000/api/v1/orchestrations \
  -H "Authorization: Bearer YOUR_API_KEY"

[
  {
    "id": "orch-research-report",
    "name": "Research → Report",
    "description": "Research a topic and generate a report",
    "steps": 5
  }
]

---

GET /api/v1/orchestrations/{orch_id}

Get full details for a specific orchestration including all step definitions.

curl http://localhost:8000/api/v1/orchestrations/orch-research-report \
  -H "Authorization: Bearer YOUR_API_KEY"

---

POST /api/v1/orchestrations/{orch_id}/run

Start an orchestration and wait for it to complete (synchronous).

Request

POST /api/v1/orchestrations/orch-research-report/run
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "message": "Synapse AI platform"
}

The message field is used as the initial input — it's passed as the starting context and typically maps to the first state key defined in state_schema.

Response — completed

{
  "status": "completed",
  "run_id": "run_orch-abc_1734567890",
  "response": "Research and report generation complete.",
  "shared_state": {
    "query": "Synapse AI platform",
    "research_results": "Synapse AI is a multi-agent...",
    "article": "# Synapse AI Platform\n\n..."
  },
  "step_history": [
    {
      "step_id": "step-research",
      "step_name": "Research",
      "type": "agent",
      "status": "completed",
      "turns": 4,
      "cost_usd": 0.015
    }
  ]
}

Response — paused (human gate)

{
  "status": "paused",
  "run_id": "run_orch-abc_1734567890",
  "human_input_required": {
    "step_id": "step-approve",
    "prompt": "Please review the draft article and decide whether to publish.",
    "fields": [
      { "name": "decision", "type": "select", "label": "Decision", "options": "approve,reject" },
      { "name": "notes", "type": "text", "label": "Editor notes" }
    ],
    "agent_context": "Draft article: ..."
  }
}

Store the run_id — you need it to resume.

Response — failed

{
  "status": "failed",
  "run_id": "run_orch-abc_1734567890",
  "response": "Cost limit exceeded: $0.52 > max $0.50"
}

---

POST /api/v1/orchestrations/{orch_id}/run/stream

Start an orchestration and receive a stream of SSE events.

curl -X POST http://localhost:8000/api/v1/orchestrations/orch-research-report/run/stream \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{"message": "quantum computing"}'

SSE event types

Type	Description
step_start	A step has begun — includes step_id, step_name, type
step_complete	A step has finished — includes output
agent_turn	Agent reasoning within a step
tool_execution	Tool call — tool_name, args
tool_result	Tool result — tool_name, preview
human_input_required	Paused for human input — includes run_id, fields
orchestration_complete	All steps done — status, final_state
orchestration_error	Error occurred — error
done	Stream ended

---

POST /api/v1/orchestrations/runs/{run_id}/resume

Submit human input and resume a paused orchestration (synchronous).

Request

POST /api/v1/orchestrations/runs/run_orch-abc_1734567890/resume
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "response": {
    "decision": "approve",
    "notes": "Excellent research, publish immediately."
  }
}

The response field is a dict matching the field names from the human_input_required payload. It can also be a plain string for simple text inputs.

Response

Same format as /run — returns completed, paused (another gate), or failed.

---

POST /api/v1/orchestrations/runs/{run_id}/resume/stream

Submit human input and resume with SSE streaming.

curl -X POST http://localhost:8000/api/v1/orchestrations/runs/{run_id}/resume/stream \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -N \
  -d '{"response": {"decision": "approve"}}'

---

Complete example: Run → Human gate → Resume

import requests

BASE = "http://localhost:8000/api/v1"
HEADERS = {"Authorization": "Bearer YOUR_KEY"}

# 1. Start the orchestration
resp = requests.post(
    f"{BASE}/orchestrations/orch-research-report/run",
    headers=HEADERS,
    json={"message": "AI orchestration trends 2025"}
)
data = resp.json()

if data["status"] == "paused":
    run_id = data["run_id"]
    human_prompt = data["human_input_required"]["prompt"]
    print(f"Human approval needed: {human_prompt}")
    
    # 2. Collect human input (e.g. from your UI)
    decision = input("Approve? (yes/no): ")
    
    # 3. Resume the orchestration
    resume_resp = requests.post(
        f"{BASE}/orchestrations/runs/{run_id}/resume",
        headers=HEADERS,
        json={"response": {"decision": decision, "notes": "Approved via API"}}
    )
    final = resume_resp.json()
    print(f"Status: {final['status']}")
    print(f"Article: {final['shared_state'].get('article', '')[:200]}...")

elif data["status"] == "completed":
    print(data["response"])