HTTP REST API - External Client Interface

Purpose

• Minimal HTTP (RESTful) interface to call orchestration in batch mode (streaming is off in v0).

Principles (clean API)

• Predictable resources and verbs (POST /orchestration/context)
• JSON only, versioned payloads ("version": "v0")
• Strict schemas, ignore unknown fields, never overshoot token budget
• Idempotency keys via request_id; correlation-friendly responses
• No streaming in v0; errors are structured in response body

Endpoint

• POST /orchestration/context
• Request body: render_request.v0 (see ../schemas/render_request.v0.json)
• Response body: render_context_reply.v0 (see ../schemas/render_context_reply.v0.json)
• Errors: structured error envelope (see ./internal.md)

Examples

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  http://localhost:8080/orchestration/context \
  -d '{
    "version": "v0",
    "id": "6f3b6f21-7a5f-4e3f-9af0-1b2c3d4e5f60",
    "intent": "explain_component_architecture",
    "budgets": { "tokens_max": 2000, "time_ms": 600 },
    "risk_profile": { "level": "low" },
    "privacy_mode": "allow",
    "request_id": "req-001"
  }'

Notes

• Keep tokens_max strict; latency is a comfort target.
• L1 requires explicit expansion with warnings surfaced upstream.