API Reference

Two services: ingestion on :8081, retrieval on :8080. Health endpoints at /health, Prometheus metrics at /metrics on both.

Ingest a claim

POST /v1/ingest

curl -X POST http://localhost:8081/v1/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "claim": {
      "claim_id": "c1",
      "tenant_id": "t1",
      "canonical_text": "Company X acquired Company Y",
      "confidence": 0.95
    },
    "evidence": [{
      "evidence_id": "e1",
      "claim_id": "c1",
      "source_id": "news://nyt/2025-09-03",
      "stance": "supports",
      "source_quality": 0.95
    }],
    "edges": []
  }'

Returns 200 OK with { "ingested_claim_id": "c1", ... }. Server-side validation: confidence and source_quality in [0.0, 1.0], valid_from <= valid_to, non-empty IDs.

Batch ingest

POST /v1/ingest/batch

Same shapes wrapped in an items array for high-volume loads.

Ingest a document

POST /v1/ingest/document

Extract claims from a raw document blob instead of hand-building payloads.

Retrieve with citations

POST /v1/retrieve

curl -X POST http://localhost:8080/v1/retrieve \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "t1",
    "query": "Company X acquired Company Y",
    "top_k": 5,
    "stance_mode": "support_only"
  }'

Field	Meaning
query	Natural-language query, or pass query_embedding for a precomputed vector
top_k	Max results
stance_mode	"balanced" (default: keep contradicted claims, demoted) or "support_only" (drop them)
time_range	{ "from_unix": ..., "to_unix": ... } validity window
entity filter	Constrain to an entity

Embeddings (OpenAI-compatible)

POST /v1/embeddings

Byte-compatible with the OpenAI v1 embeddings API. Default backend is the deterministic HashEmbeddingProvider (no network, no key); swap via DASH_EMBEDDING_PROVIDER=hash|ollama|openai or a custom EmbeddingProvider trait implementation.

curl -X POST http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"input": "Company X acquired Company Y", "model": "text-embedding-3-small"}'

Any OpenAI client works by pointing base_url / OPENAI_API_BASE at http://localhost:8080/v1.

Health and metrics

GET /health
GET /metrics

Health on both services; Prometheus metrics include ingest/retrieve throughput, ANN recall, and WAL replay stats.