Connect your tool (API & MCP)

Everything you need to call Housecarl Arbiter from your own software — the developer path.

Two ways to call

The engine has one core operation — submit an investigation, get back a scored verdict — exposed two equivalent ways. Both use the same request shape and the same credentials; pick whichever fits what you're building.

• REST / JSON over HTTPS — A plain POST with a JSON body. Best for a backend service, a script, or any non-AI tool. Start here.
• MCP — The Model Context Protocol endpoint at /mcp/v1 (Streamable HTTP, JSON-RPC 2.0). Best if your tool is an AI agent that already speaks MCP.

Authenticate

Sign in, open Connection in the console, and create an API key. It starts with se- and is shown once at creation — store it as a secret. Send it on every request in the x-api-key header:

x-api-key: se-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

OAuth 2.0 / JWT bearer tokens are also accepted via the Authorization: Bearer header, but a user API key is the simplest path for a standalone integration.

Quickstart

The smallest useful call — one source, one subject, one claim. The response is a full investigation result: a per-subject verdict, ranked claims, conflict analysis, and sensitivity analysis.

curl -sS -X POST https://api.arbiter.housecarl.cloud/api/v1/investigations/analyze \
  -H "x-api-key: se-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "research_question": "Is Acme Corp solvent?",
    "domain": "Finance",
    "actors": [
      { "id": "auditor", "name": "Big Four Auditor",
        "source_type": "Regulator", "base_reliability": 0.9 }
    ],
    "subjects": [
      { "id": "acme", "name": "Acme Corp", "subject_type": "company" }
    ],
    "claims": [
      { "id": "c1", "actor_id": "auditor", "subject_id": "acme",
        "predicate": "solvency", "value": "solvent",
        "content": "Audited financials show a 2:1 current ratio.",
        "valence": "Supports", "assertion_time": "2026-02-01T10:00:00Z" }
    ]
  }'

Core endpoints

Base URL https://api.arbiter.housecarl.cloud. All paths require authentication.

Method	Path	Description
POST	/api/v1/investigations/analyze	One-shot analysis
POST	/api/v1/sessions	Create a persistent session
PATCH	/api/v1/sessions/{id}	Merge in new actors / claims / evidence
POST	/api/v1/sessions/{id}/judge	Re-run the engine on the session
PUT	/api/v1/sessions/{id}/share	Publish a read-only snapshot

Use /investigations/analyze for one-off questions. If your system accumulates evidence over time, create a session, merge in claims as you learn them, and re-judge on demand instead of resubmitting the whole payload.

Good to know

• Always set each claim's valence (Supports / Refutes) and assertion_time — they drive the result more than anything else.
• Inconsistent inputs (e.g. an anonymous source rated 0.95) come back as non-fatal warnings; the run still succeeds. An empty warnings list means clean input.
• Set summary_mode: true for a compact result when your consumer has a limited context window.
• Up to 1,024 sessions per user; payloads up to 10 MB; sessions expire after 365 days of inactivity.
• A 429 means your plan quota is exhausted; a 504 means the input was too large — split it up.

API reference

Interactive API documentation with request/response schemas, authentication details, and the full OpenAPI spec.

api.arbiter.housecarl.cloud/openapi-docs

Need a payload to send? The extraction prompt turns any source text into a ready-to-submit investigation JSON, and the worked example shows a full one end to end.