REST API Guide

Everything the SDK does is a thin wrapper over this REST API — you can integrate without the SDK using any HTTP client. This page gives curl examples for the core flow. The engine serves the full, always-current schema at $CARC_RUNTIME_API_URL/openapi.json and the interactive reference at $CARC_RUNTIME_API_URL/docs.

Set CARC_RUNTIME_API_URL to the runtime engine origin before using the examples. For local development, start the engine with npm run dev:engine and set the variable to its printed origin.

Headers

Header	Purpose
Authorization: Bearer <token>	Accepted, not yet enforced. See Security.
X-Tenant-ID	Scopes the request to a tenant. Falls back to the engine's default tenant. Not a security boundary.
X-Correlation-ID	Optional; generated if omitted, always echoed back.

Agent registration

curl -X POST ${CARC_RUNTIME_API_URL}/runtime/agents \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: tenant_acme_health" \
  -d '{
    "agent_id": "acme-radiology-copilot",
    "name": "Acme Radiology Copilot",
    "owner": "acme-health-ai",
    "version": "1.0.0",
    "clinical_domain": "radiology",
    "allowed_tasks": ["radiology_follow_up_recommendation"],
    "capabilities": ["summarize_findings"],
    "model_provider": "acme-ai",
    "model_version": "v3",
    "risk_tier": "high"
  }'

Agent activation

curl -X POST ${CARC_RUNTIME_API_URL}/runtime/agents/acme-radiology-copilot/activate \
  -H "X-Tenant-ID: tenant_acme_health"

External Agent Run submission

curl -X POST ${CARC_RUNTIME_API_URL}/runtime/agent-runs \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: tenant_acme_health" \
  -d '{
    "agent_id": "acme-radiology-copilot",
    "case_id": "acme-case-4471",
    "task_type": "radiology_follow_up_recommendation",
    "model_provider": "acme-ai",
    "model_version": "v3",
    "source_references": [{
      "source_id": "src-1",
      "source_type": "chart_note",
      "title": "Radiology report",
      "content": "CT chest shows a 6mm nodule, indeterminate.",
      "authored_at": "2026-07-01T00:00:00.000Z"
    }],
    "agent_output": {
      "identity": {
        "agent_id": "acme-radiology-copilot",
        "agent_version": "1.0.0",
        "model_provider": "acme-ai",
        "model_version": "v3",
        "task_type": "radiology_follow_up_recommendation"
      },
      "generated_at": "2026-07-10T00:00:00.000Z",
      "narrative": "Repeat CT imaging in three months.",
      "claims": [{
        "claim_id": "claim-1",
        "claim_type": "follow_up",
        "statement": "Repeat CT imaging in three months.",
        "supporting_source_ids": ["src-1"]
      }],
      "medication_recommendations": [],
      "discharge_instructions_present": false
    }
  }'

The response includes session_id, run_id, decision_id, control_action, risk_score/risk_level, review_required, and the full policy_results/evidence_results.

Managed execution (Initiative 1)

The platform executes a registered agent through its configured provider adapter and submits the result directly into Runtime Control — see Model Provider Adapters for how this differs from the bring-your-own-execution example above.

curl -X POST ${CARC_RUNTIME_API_URL}/runtime/agents/openai-discharge-summary-agent/execute \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: tenant_acme_health" \
  -d '{
    "case_id": "case-openai-discharge-ambiguous",
    "task_type": "discharge_summary",
    "instructions": "Draft a discharge summary.",
    "source_references": [{
      "source_id": "src-0003-chart-1",
      "source_type": "chart_note",
      "title": "Post-Operative Progress Note, Day 4",
      "content": "67F post right total knee arthroplasty day 4, ambulating independently, pain controlled.",
      "authored_at": "2026-07-05T08:30:00.000Z"
    }]
  }'

The response includes adapter_id, execution_profile_id, connection_id, model_provider, model_version, and execution_metadata (token counts, latency, provider request id, finish reason) in addition to the same control_action/risk_score/policy_results/evidence_results fields the bring-your-own path returns. Requires the agent to have an execution_profile_id set, and that profile to have both adapter_id and provider_connection_id set — see Execution Profiles and Provider Connections below.

Adapter Registry

# List every registered adapter (secret-free)
curl ${CARC_RUNTIME_API_URL}/runtime/adapters -H "X-Tenant-ID: tenant_acme_health"

# Get one adapter
curl ${CARC_RUNTIME_API_URL}/runtime/adapters/openai-responses-adapter -H "X-Tenant-ID: tenant_acme_health"

# Re-validate configuration (e.g. after setting OPENAI_API_KEY)
curl -X POST ${CARC_RUNTIME_API_URL}/runtime/adapters/openai-responses-adapter/validate -H "X-Tenant-ID: tenant_acme_health"

Provider Connections (Initiative 2)

Customer-owned model credentials — see Provider Connections for the full architecture. credential is write-only and never returned. Contains no model/execution configuration — see Execution Profiles below.

# Create a tenant-owned connection
curl -X POST ${CARC_RUNTIME_API_URL}/runtime/provider-connections \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: tenant_acme_health" \
  -d '{
    "provider": "openai",
    "display_name": "Acme Health — OpenAI Production",
    "credential": "sk-REDACTED-EXAMPLE-ONLY"
  }'

# Validate it (presence/shape only, no live provider call)
curl -X POST ${CARC_RUNTIME_API_URL}/runtime/provider-connections/pcn_xxx/validate -H "X-Tenant-ID: tenant_acme_health"

Execution Profiles (Initiative 3)

The canonical execution contract — see Execution Profiles for the full architecture and the 19-step managed-execution resolution order.

# Create an execution profile referencing the connection above
curl -X POST ${CARC_RUNTIME_API_URL}/runtime/execution-profiles \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: tenant_acme_health" \
  -d '{
    "display_name": "GPT-5 Structured Clinical",
    "provider": "openai",
    "adapter_id": "openai-responses-adapter",
    "provider_connection_id": "pcn_xxx",
    "model": "gpt-5",
    "temperature": 0.2,
    "max_output_tokens": 2048
  }'

# Activate it
curl -X POST ${CARC_RUNTIME_API_URL}/runtime/execution-profiles/exp_xxx/activate -H "X-Tenant-ID: tenant_acme_health"

# Link it to an agent
curl -X PATCH ${CARC_RUNTIME_API_URL}/runtime/agents/acme-discharge-summary-agent \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: tenant_acme_health" \
  -d '{ "execution_profile_id": "exp_xxx" }'

Session retrieval

curl ${CARC_RUNTIME_API_URL}/runtime/sessions/{session_id} -H "X-Tenant-ID: tenant_acme_health"

Approval

curl -X POST ${CARC_RUNTIME_API_URL}/runtime/sessions/{session_id}/approve \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: tenant_acme_health" \
  -d '{"reviewer_id": "dr.reviewer", "notes": "Approved."}'

Rejection

curl -X POST ${CARC_RUNTIME_API_URL}/runtime/sessions/{session_id}/reject \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: tenant_acme_health" \
  -d '{"reviewer_id": "dr.reviewer", "notes": "Not approved."}'

Retry

curl -X POST ${CARC_RUNTIME_API_URL}/runtime/sessions/{session_id}/retry \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: tenant_acme_health" \
  -d '{"reviewer_id": "dr.reviewer", "notes": "Retrying with corrected context."}'

Decision record retrieval

curl ${CARC_RUNTIME_API_URL}/runtime/decision-records/{decision_id} -H "X-Tenant-ID: tenant_acme_health"

Replay retrieval

# Single-run replay
curl ${CARC_RUNTIME_API_URL}/runtime/decision-records/{decision_id}/replay -H "X-Tenant-ID: tenant_acme_health"

# Full multi-run session replay
curl ${CARC_RUNTIME_API_URL}/runtime/sessions/{session_id}/replay -H "X-Tenant-ID: tenant_acme_health"

Metrics retrieval

curl "${CARC_RUNTIME_API_URL}/runtime/metrics?agent_id=acme-radiology-copilot" -H "X-Tenant-ID: tenant_acme_health"

Next

• Errors — response shapes for 400/404/409/500
• Integration Patterns