API Reference

TheoremSearch exposes a REST API for semantic theorem search, dependency graph exploration, and paper lookup. All endpoints are available at the base URL below.

BASE URL

https://api.theoremsearch.com

POST

Search

POST/search

Perform semantic search for mathematical theorems. Embeds the query using Qwen3-Embedding-8B, runs HNSW approximate nearest-neighbor search, then reranks by exact cosine similarity with optional citation weighting.

REQUEST BODY

FIELD	TYPE	DEFAULT	DESCRIPTION
query*	string	—	Natural-language description of the mathematical result to find.
n_results	integer	10	Number of theorems to return.
sources	string[]	[]	Filter by source. Options: arXiv, Stacks Project, ProofWiki, CRing Project, HoTT Book, Open Logic Project, An Infinitely Large Napkin.
authors	string[]	[]	Filter by author name (partial match).
types	string[]	[]	Filter by theorem type, e.g. Theorem, Lemma, Proposition, Corollary.
tags	string[]	[]	Filter by primary arXiv category, e.g. math.AG.
paper_filter	string \| null	null	Filter results to theorems from papers whose title contains this substring.
year_range	[int, int] \| null	null	Inclusive year range, e.g. [2015, 2023].
citation_range	[int, int] \| null	null	Inclusive citation count range, e.g. [10, 500].
include_unknown_citations	boolean	true	When filtering by citation_range, whether to include papers with no citation data.
citation_weight	number	0.0	Blends ln(citations) into the ranking score. 0 = pure semantic similarity.
prompt	string \| null	null	Instruction prepended to the query before embedding. Defaults to the built-in search prompt.
db_top_k	integer \| null	null	ANN candidate pool size before reranking. Higher improves recall at cost of latency. Defaults to 2 × n_results.

EXAMPLE

curl https://api.theoremsearch.com/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "smooth DM stack codimension one",
    "n_results": 5,
    "sources": ["Stacks Project"],
    "year_range": [2010, 2024]
  }'

RESPONSE

{
  "theorems": [
    {
      "slogan_id": 8291,
      "theorem_id": 5104,
      "name": "Lemma 4.2",
      "body": "Let X be a smooth DM stack...",
      "slogan": "A smooth DM stack has a dense open subscheme.",
      "theorem_type": "Lemma",
      "link": "https://stacks.math.columbia.edu/tag/04YC",
      "similarity": 0.871,
      "score": 0.871,
      "paper": {
        "source": "Stacks Project",
        "title": "Stacks Project",
        "primary_category": "math.AG",
        "year": null,
        "citations": null,
        "journal_published": null
      }
    }
  ]
}

GET

Graph

GET/graph?external_id={id}

Returns the full dependency graph for a paper — all its formal statements, and the directed edges showing which statements depend on which (including cross-paper citations).

QUERY PARAMETERS

FIELD	TYPE	DEFAULT	DESCRIPTION
external_id*	string	—	arXiv ID or other external paper identifier, e.g. 2403.05555.

EXAMPLE

curl "https://api.theoremsearch.com/graph?external_id=2403.05555"

RESPONSE

{
  "paper": {
    "paper_id": "uuid",
    "title": "Paper Title",
    "external_id": "2403.05555",
    "source": "arXiv",
    "url": "https://arxiv.org/abs/2403.05555",
    "authors": ["Author One", "Author Two"],
    "abstract": "..."
  },
  "statements": [
    {
      "statement_id": "uuid",
      "name": "Theorem 1.1",
      "body": "Let R be a ring...",
      "note": "Informal description or null",
      "proof": "Proof text or null"
    }
  ],
  "dependencies": [
    {
      "src_statement_id": "uuid",
      "src_name": "Theorem 1.1",
      "dep_statement_id": "uuid",
      "dep_name": "Lemma 2.3",
      "dep_paper_ext_id": "2401.00001",
      "dep_paper_title": "Another Paper",
      "interpaper": true
    }
  ]
}

interpaper: true on a dependency edge means the referenced statement lives in a different paper.

GET

Paper Search

GET/paper-search?q={query}&limit={n}

Autocomplete search over paper titles and external IDs. Returns exact external-ID prefix matches first, then title substring matches.

QUERY PARAMETERS

FIELD	TYPE	DEFAULT	DESCRIPTION
q	string	""	Search string matched against external ID (prefix) and title (substring).
limit	integer	8	Maximum number of results to return.

EXAMPLE

curl "https://api.theoremsearch.com/paper-search?q=derived+categories&limit=5"

RESPONSE

{
  "papers": [
    {
      "paper_id": "uuid",
      "title": "Derived Categories of Coherent Sheaves",
      "external_id": "math/0206163",
      "source": "arXiv"
    }
  ]
}

GET

Paper Links

GET/paper-links

Returns all directed citation edges among papers in the graph dataset as source → target pairs of paper UUIDs. Useful for constructing citation network visualizations.

EXAMPLE

curl https://api.theoremsearch.com/paper-links

RESPONSE

{
  "links": [
    { "source": "uuid-of-citing-paper", "target": "uuid-of-cited-paper" }
  ]
}

MCP

TheoremSearch is available as an MCP (Model Context Protocol) server for AI agents. It exposes a single tool theorem_search with the same parameters as POST /search.

ENDPOINThttps://api.theoremsearch.com/mcp

EXAMPLE — CALL theorem_search VIA MCP

curl -X POST https://api.theoremsearch.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "theorem_search",
      "arguments": {
        "query": "every projective module over a local ring is free",
        "n_results": 5
      }
    }
  }'

RESPONSE

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "content": [{ "type": "text", "text": "{...serialized SearchResponse...}" }],
    "structuredContent": { "theorems": [...] }
  }
}

SUPPORTED METHODS

FIELD	TYPE	DEFAULT	DESCRIPTION
initialize	—	—	Handshake. Returns protocol version and server capabilities.
tools/list	—	—	Returns the theorem_search tool schema.
tools/call	—	—	Invokes theorem_search with the given arguments.