Alexandria Library API

Overview

The Library is a typed, provenance-backed, confidence-rated knowledge graph across all fields. It serves as an agent-native alternative to web search: instead of returning documents, it returns resolved, deduped, cited answer bundles with belief differences surfaced.

334 nodes, 440 edges, 9 MCP tools, growing daily via automated ingestion from arXiv, Wikipedia, and Semantic Scholar.

Authentication

All endpoints require Authorization: Bearer <token>. No token = 402 Payment Required with x402 payload.

In dev mode, use the dev token (default: alex-dev-token, set via ALEX_DEV_PAYMENT_TOKEN env var). In production, the x402 flow handles payment automatically.

Pricing

All prices in USDC via x402. Dev token bypasses all pricing.

catalog

GET /api/catalog

Machine-readable capability descriptor. Returns node/edge counts by type, top tags, trust posture, and priced routes. An agent reads this to discover what the Library holds before paying.

{
  "schema_ver": "catalog/v1",
  "content": {
    "nodes": 334,
    "by_type": {"Paper": 108, "Strategy": 37, ...},
    "top_tags": [["deep-learning", 27], ...]
  },
  "trust": {"avg_confidence": 0.829},
  "pricing": {"query.nodes": {"cents": 0, "asset": "USDC"}, ...}
}

query

GET POST /api/query

Declarative query. Returns typed artifacts, ids, or a cited summary.

{
  "intent": "nodes | edges | graph",
  "filters": {
    "types": ["Paper", "Result"],
    "tags": ["momentum"],
    "min_confidence": 0.7,
    "since": "ISO8601"
  },
  "output_shape": "artifact | summary | ids",
  "limit": 20
}

retrieve

GET /api/retrieve?artifact_id=

Fetch one artifact by stable id. Returns the full CONTRACT §3 artifact JSON.

assemble

GET POST /api/assemble

Resolve a target and return a compact, cited answer bundle. Resolves by id, alias, title, or sparse similarity. Walks the typed graph, dedupes by entity, groups by role, and surfaces belief differences.

{
  "target": "momentum investing",
  "depth": 1,
  "min_confidence": 0.7,
  "include_summaries": false
}

resolve_and_fetch

GET POST /api/resolve_and_fetch

Resolve with fallback to live sources. When the library misses, fires Wikipedia, arXiv, and web search in parallel. Returns a bundle-like result with a source field.

{
  "target": "YC startup AI coding agent",
  "max_fallbacks": 3,
  "depth": 1
}

traverse

GET /api/traverse?node_id=

Return the typed neighborhood of a single entity. The agent walks the knowledge graph interactively, one hop at a time. Groups neighbors by role (support, risks, assumptions, depends_on, belief_differences, related).

{
  "node_id": "strategy-momentum-investing",
  "min_confidence": 0.7
}

compare

GET /api/compare?entity_a=&entity_b=

Compare two entities. Returns direct edges, shared neighbors, belief differences, provenance overlap, shared tags, and a structured comparison summary. No other MCP tool does this.

{
  "entity_a": "paper-jegadeesh-titman-1993",
  "entity_b": "paper-moskowitz-ooi-pedersen-2012"
}

pathfind

GET /api/pathfind?entity_a=&entity_b=

Find the shortest typed path between two entities through the graph. Uses bidirectional BFS. Returns typed hops with relation labels and a natural language summary.

{
  "entity_a": "strategy-momentum-investing",
  "entity_b": "paper-sharpe-1964-capm",
  "max_depth": 4
}

trending

GET /api/trending

Return the trending snapshot — what agents are asking about most, top types and tags, query volume, and conversion rates. Telemetry is anonymized and aggregated.

health

GET /health

Provider + gate status. No auth required.

MCP (stdio transport)

Add to your MCP client config:

{
  "mcpServers": {
    "alexandria": {
      "command": "python",
      "args": ["-m", "library.mcp.server"],
      "env": {
        "ALEX_DEV_PAYMENT_TOKEN": "your-token"
      }
    }
  }
}

Tools: library_query, library_retrieve, library_assemble, library_catalog, library_resolve_and_fetch, library_traverse, library_compare, library_pathfind, library_trending.

MCP (SSE transport)

Remote agents connect via Server-Sent Events:

curl -N https://your-library.com/api/sse/mcp

Send JSON-RPC messages via POST:

curl -X POST https://your-library.com/api/sse/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

HTTP API

Deploy guide

# Prerequisites: wrangler CLI, logged in (or CLOUDFLARE_API_TOKEN)
./deploy.sh

This creates the D1 database, seeds the corpus, deploys the Worker, and deploys the static site. See deploy.sh for details.

Wallet onboarding

See docs/agent-wallet-onboarding.md for wallet setup instructions.