LOGOI

Documentation

API

Overview

Logoi exposes four public surface families. All JSON responses carry X-Robots-Tag: noindex, nofollow — they are agent contracts, not public evidence pages. The complete machine-readable description lives at /openapi.json (OpenAPI 3.1).

  • POST /api/v1/ask — ask the corpus a question; answer streams as SSE with citations.
  • GET /api/v1/coverage — the living per-work corpus inventory.
  • POST /api/mcp — Model Context Protocol transport for agents (see MCP docs).
  • GET /api/v1/tools — the same eighteen MCP tool definitions as a cacheable JSON catalog.
  • GET /api/public/evidence-chains/{slug}.json — an exact checked-in receipt DAG with no D1 or provider execution.

POST /api/v1/ask

Body: {"query": "..."} (max 500 characters). Response: text/event-stream. The event sequence:

  • meta — query_id, model, ai_authored disclosure, quota state
  • token — streaming answer text delta
  • tool — corpus tool call in progress (name + input)
  • citations — source_ids plus either receipt_url or an explicit unavailable receipt state attached to a tool result
  • done — final query_id, stop_reason, usage, quota
  • error — query_id, message, refunded flag (failed queries refund quota)
curl -N -X POST https://logoi.health/api/v1/ask \
  -H 'Content-Type: application/json' \
  -d '{"query": "How often does thumos occur in the Odyssey?"}'

Quotas: every visitor gets 40 queries/day with a 60/minute burst brake. Estate members (an X-Member-Key header the shared estate ledger recognizes; check one at POST /api/v1/member/check) skip the daily count but keep the brake. An email account (/login, magic link) syncs saved passages — it does not change the AI quota.

GET /api/v1/coverage

Returns the living per-work inventory generated from the production database (contract corpus_coverage_v0, cached five minutes at the edge). Check it before making absence claims: a work missing here is unindexed, not unattested in antiquity. The human-browsable version is /corpus.

Honesty contract

  • Every answer is built from corpus tool calls; source_ids and either a materialized receipt_url or an explicit unavailable receipt state ride along as citations events.
  • Logoi does not reproduce copyrighted source text in API responses.
  • Words absent from the indexed corpus return "not attested" — an honest empty result, not an invention.

See the citation policy for how to cite Logoi output, and /llms.txt for the condensed machine-discovery document.

GET /api/public/evidence-chains/{slug}.json

Returns the deterministic receipt-identity graph behind one bounded instrument result: custody, bibliography pointer, source authority, passage evidence, and result receipt. Each node carries its exact content SHA-256 and assertion scope; every edge must reproduce ancestry declared by its descendant receipt. The graph is a navigation and integrity projection, not a composite receipt or wider authority.

Legacy endpoints

The older /api/public/* reference-pointer endpoints remain reachable but deprecated. The checked-in evidence-chain endpoint above is the deliberate exception: it serves a current, bounded integrity projection and is documented separately in /openapi.json. New corpus integrations should still use /api/v1/* and MCP.