Raw HTTP

Use raw HTTP when you need a language-neutral integration. The HTTP surface is the source of truth behind the SDK and MCP bridge.

Core Path


POST /v1/observe
POST /v1/guide
POST /v1/feedback
POST /v1/measure
POST /v1/operator/snapshot

Run the quickstart:


npm run -s runtime:quickstart:http

Health


curl -s http://127.0.0.1:3001/health

The Lite Runtime redacts local store paths from public health snapshots.

Observe


curl -s http://127.0.0.1:3001/v1/observe \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "checkout-migration",
    "input_text": "Prefer concise product updates with concrete next steps.",
    "memory_lane": "private",
    "owner_agent_id": "agent-1"
  }'

Guide


curl -s http://127.0.0.1:3001/v1/guide \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "checkout-migration",
    "mode": "full_power",
    "context_mode": "compact_agent",
    "query_text": "Continue the checkout migration.",
    "consumer_agent_id": "agent-1",
    "limit": 8
  }'

Use agent_context.prompt_text as the Agent-facing context. Preserve guide_trace_id for feedback attribution.

Feedback


curl -s http://127.0.0.1:3001/v1/feedback \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "checkout-migration",
    "target": "memory",
    "guide_trace_id": "guide_trace:...",
    "run_id": "run-001",
    "outcome": "positive",
    "used_surface": "use_now",
    "used_memory_ids": ["mem_123"],
    "reason": "The Agent used the exposed current-state memory successfully."
  }'

Feedback is rejected if used_memory_ids were not exposed by the referenced guide.

Measure And Snapshot


curl -s http://127.0.0.1:3001/v1/measure \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "checkout-migration",
    "task": {
      "run_id": "run-001",
      "task_signature": "checkout-migration"
    },
    "product_trace": {
      "after_guide": {"guide_trace_id": "guide_trace:..."},
      "feedback_result": {"outcome": "positive"},
      "sufficient_evidence": true
    }
  }'


curl -s http://127.0.0.1:3001/v1/operator/snapshot \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "checkout-migration",
    "run_id": "run-001",
    "task_signature": "checkout-migration",
    "include_markdown": true
  }'

Auth Header

Lite mode normally runs without auth on loopback. When a key is configured, send both forms for compatibility:


-H "authorization: Bearer $AIONIS_API_KEY" \
-H "x-api-key: $AIONIS_API_KEY"

Guide: AIONIS_HTTP_QUICKSTART.md .