{
  "openapi": "3.1.0",
  "info": {
    "title": "thequant.space research corpus API",
    "version": "1.0.0",
    "summary": "Query 5,000+ scored quantitative-finance research papers.",
    "description": "thequant.space scores quant-finance papers from arXiv q-fin and SSRN on two 0-10 axes, math_complexity and empirical_rigor, assigns a quadrant (Holy Grail / Street Traders / Lab Rats / Philosophers), topic hubs, method and asset-class labels, and publishes a plain-language summary, a written score rationale and a Mermaid research flowchart per paper. hub_score = 0.6*empirical_rigor + 0.4*math_complexity is the default ranking. Scores are LLM-assisted rubric judgements, not peer review (https://thequant.space/score-guide/). No authentication. Responses are cached at the edge for up to an hour; the corpus updates daily. Free for personal and research use with attribution to thequant.space; terms at https://thequant.space/agents/. An MCP server with the same capabilities is at https://thequant.space/mcp.",
    "contact": {
      "url": "https://thequant.space/about/"
    },
    "license": {
      "name": "Free for personal and research use with attribution",
      "url": "https://thequant.space/agents/"
    }
  },
  "servers": [
    {
      "url": "https://thequant.space"
    }
  ],
  "paths": {
    "/api/papers": {
      "get": {
        "operationId": "searchPapers",
        "summary": "Search and filter scored papers",
        "description": "Returns compact paper records (no abstract or flowchart) plus the total match count. Combine filters freely. Use min_rigor=7 for credible empirical work and has_code=true for reproducible papers. Records carry the paper's reported performance (reports_backtest, sharpe, annual_return_pct, max_drawdown_pct, sample_start, sample_end, transaction_costs, out_of_sample) when it discloses a backtest; these are the authors' own claims, LLM-extracted and verified verbatim against the paper, not reproduced. Records also carry execution-realism flags (evaluation_type, tcost_modeled, oos_method, data_resolution) and, when the Empirical Rigor cap applied, empirical_rigor_raw and rigor_cap_reason (https://thequant.space/score-guide/#penalty-flags).",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Free-text search over title, abstract, keywords and authors. Terms are ANDed.",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "topic",
            "in": "query",
            "description": "Topic-hub slug (see /api/topics).",
            "schema": {
              "type": "string"
            },
            "example": "market-microstructure"
          },
          {
            "name": "method",
            "in": "query",
            "description": "Method slug (see /api/methods).",
            "schema": {
              "type": "string"
            },
            "example": "deep-learning"
          },
          {
            "name": "asset",
            "in": "query",
            "description": "Asset-class slug.",
            "schema": {
              "type": "string",
              "enum": [
                "equities",
                "macro-multi-asset",
                "derivatives",
                "crypto",
                "fixed-income",
                "insurance",
                "credit",
                "commodities-energy",
                "fx",
                "esg-climate",
                "private-markets",
                "real-estate"
              ]
            }
          },
          {
            "name": "quadrant",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "Holy Grail",
                "Street Traders",
                "Lab Rats",
                "Philosophers"
              ]
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Paper type from the classifier.",
            "schema": {
              "type": "string",
              "enum": [
                "empirical",
                "theoretical",
                "methodological",
                "survey-review",
                "perspective-policy",
                "dataset-benchmark",
                "software-tool"
              ]
            }
          },
          {
            "name": "author",
            "in": "query",
            "description": "Author name substring.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "min_rigor",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 10
            }
          },
          {
            "name": "max_rigor",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 10
            }
          },
          {
            "name": "min_math",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 10
            }
          },
          {
            "name": "max_math",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 10
            }
          },
          {
            "name": "since",
            "in": "query",
            "description": "Earliest paper date.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "until",
            "in": "query",
            "description": "Latest paper date.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "has_code",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "has_backtest",
            "in": "query",
            "description": "Only papers that report (true) or do not report (false) a backtest of their own strategy on real market data.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "has_sharpe",
            "in": "query",
            "description": "Only papers that disclose a Sharpe ratio for their own strategy.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "min_sharpe",
            "in": "query",
            "description": "Reported Sharpe ratio at least this.",
            "schema": {
              "type": "number",
              "minimum": -10,
              "maximum": 50
            }
          },
          {
            "name": "max_sharpe",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": -10,
              "maximum": 50
            }
          },
          {
            "name": "min_annual_return",
            "in": "query",
            "description": "Reported annualized return (%) at least this.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "max_drawdown",
            "in": "query",
            "description": "Reported maximum drawdown (%) at most this.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            }
          },
          {
            "name": "tcost_modeled",
            "in": "query",
            "description": "Transaction costs applied to the reported results (decision-model flag). Comma-separate several values. Values: yes, partial, no, n/a, unclear.",
            "schema": {
              "type": "string",
              "example": "yes"
            }
          },
          {
            "name": "oos_method",
            "in": "query",
            "description": "Out-of-sample validation of the reported results. Values: holdout, walk-forward, cross-validation, none, unclear.",
            "schema": {
              "type": "string",
              "example": "holdout"
            }
          },
          {
            "name": "data_resolution",
            "in": "query",
            "description": "Finest resolution of market data used in the evaluation. Values: l2-book, tick, intraday-bars, daily, weekly-monthly, synthetic, none, unclear.",
            "schema": {
              "type": "string",
              "example": "l2-book"
            }
          },
          {
            "name": "evaluation_type",
            "in": "query",
            "description": "Headline empirical result. Values: trading-pnl, execution-cost, forecast-accuracy, pricing-calibration, none.",
            "schema": {
              "type": "string",
              "example": "trading-pnl"
            }
          },
          {
            "name": "rigor_capped",
            "in": "query",
            "description": "true: only papers whose empirical_rigor was capped at 6.0 (trading/execution results without modelled transaction costs, or trading/execution/forecast results without out-of-sample testing); empirical_rigor_raw holds the uncapped score. false: only uncapped papers.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Default: relevance when q is given, otherwise hub_score. sharpe, annual_return and drawdown sort by the paper's reported figures, papers without one last.",
            "schema": {
              "type": "string",
              "enum": [
                "hub_score",
                "rigor",
                "math",
                "date",
                "sharpe",
                "annual_return",
                "drawdown",
                "relevance"
              ]
            }
          },
          {
            "name": "order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "desc",
                "asc"
              ],
              "default": "desc"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching papers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaperList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/papers/{id}": {
      "get": {
        "operationId": "getPaper",
        "summary": "Get one paper's full record",
        "description": "Abstract, summary, the written 'why this score' rationale, the Mermaid research flowchart, all labels, and five related papers from the same hub.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "arXiv id (2409.01234), SSRN id (ssrn-1234567), or an arXiv abs/pdf URL.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The paper.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaperFull"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/topics": {
      "get": {
        "operationId": "listTopics",
        "summary": "List topic hubs",
        "description": "The topic hubs with slug, description, paper count, share of papers with empirical rigor >= 7, hub URL and per-topic data file.",
        "responses": {
          "200": {
            "description": "Topic hubs.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HubList"
                }
              }
            }
          }
        }
      }
    },
    "/api/methods": {
      "get": {
        "operationId": "listMethods",
        "summary": "List method hubs",
        "description": "The method hubs with description, counts, rigor share, and the slugs of the guides that teach each method's evaluation pitfalls.",
        "responses": {
          "200": {
            "description": "Method hubs.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HubList"
                }
              }
            }
          }
        }
      }
    },
    "/api/stats": {
      "get": {
        "operationId": "corpusStats",
        "summary": "Corpus statistics",
        "description": "Totals, counts by quadrant, by year (with average rigor), by paper type, and the last update date. Includes reported_performance: how many papers disclose a backtest / Sharpe / annual return, the maximum reported Sharpe and annual return, and the papers behind them.",
        "responses": {
          "200": {
            "description": "Statistics.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "operationId": "semanticSearch",
        "summary": "Semantic search over papers, guides, tools and posts",
        "description": "Meaning-based hybrid (vector + keyword) search over the full text of every paper page, practitioner guide, learning path, calculator and post, backed by Cloudflare AI Search. Use it for natural-language questions or when /api/papers?q= finds nothing; use /api/papers for structured filters. Responses are edge-cached per query for an hour. Metered upstream: a daily budget applies and returns 429 when exhausted (keyword search on /api/papers keeps working).",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Natural-language query.",
            "schema": {
              "type": "string",
              "maxLength": 300
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 10
            }
          },
          {
            "name": "kind",
            "in": "query",
            "description": "Restrict to one page kind.",
            "schema": {
              "type": "string",
              "enum": [
                "paper",
                "guide",
                "path",
                "tool",
                "post",
                "page"
              ]
            }
          },
          {
            "name": "min_score",
            "in": "query",
            "description": "Drop matches below this relevance score.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          },
          {
            "name": "rewrite",
            "in": "query",
            "description": "Let the service rewrite the query for retrieval first.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked pages.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "string"
                    },
                    "search_query": {
                      "type": "string",
                      "description": "The query actually run (after optional rewriting)."
                    },
                    "count": {
                      "type": "integer"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "paper",
                              "guide",
                              "path",
                              "tool",
                              "post",
                              "page"
                            ]
                          },
                          "title": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "score": {
                            "type": "number"
                          },
                          "snippet": {
                            "type": "string"
                          },
                          "matched_chunks": {
                            "type": "integer"
                          },
                          "paper_id": {
                            "type": "string"
                          },
                          "paper_date": {
                            "type": "string"
                          },
                          "quadrant": {
                            "type": "string"
                          },
                          "math_complexity": {
                            "type": "number"
                          },
                          "empirical_rigor": {
                            "type": "number"
                          },
                          "hub_score": {
                            "type": "number"
                          },
                          "topics": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "methods": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "paper_url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "code_url": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    },
                    "engine": {
                      "type": "string"
                    },
                    "docs": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters."
          },
          "429": {
            "description": "Daily semantic-search budget exhausted."
          },
          "502": {
            "description": "Upstream search failed."
          }
        }
      }
    },
    "/api/chat": {
      "post": {
        "operationId": "askCorpus",
        "summary": "Ask a question, answered from the corpus with cited sources (streaming)",
        "description": "Retrieval-augmented answer over every paper page, guide, learning path, calculator and post (Cloudflare AI Search retrieval, Llama 3.3 70B generation on Workers AI). The model answers only from the retrieved pages and cites them as markdown links. The response is a text/event-stream of lines `data: {\"response\": \"<token>\"}`; concatenate the tokens. Multi-turn: send the prior turns too (max 10 messages, 2,000 characters each); the last user message is the retrieval query. Metered: 5 requests per minute and 60 per day per client, 500 per day overall; 429 when exceeded. For a non-streaming JSON answer with a sources array use the MCP tool ask_papers. Aggregate questions (how many papers disclose a Sharpe ratio, the highest reported annual return, average drawdown, top-N) are detected and answered exactly from the database with linked papers instead of retrieval; the response carries X-Answer-Engine: sql.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "messages"
                ],
                "properties": {
                  "messages": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 10,
                    "items": {
                      "type": "object",
                      "required": [
                        "role",
                        "content"
                      ],
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "user",
                            "assistant"
                          ]
                        },
                        "content": {
                          "type": "string",
                          "maxLength": 2000
                        }
                      }
                    }
                  }
                }
              },
              "example": {
                "messages": [
                  {
                    "role": "user",
                    "content": "Does momentum survive transaction costs in crypto?"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Server-sent events; each `data:` line is a JSON object with a `response` token.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid body."
          },
          "429": {
            "description": "Rate or budget limit; see Retry-After."
          },
          "502": {
            "description": "Upstream retrieval or generation failed."
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "BadRequest": {
        "description": "Invalid parameter.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "No such paper.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "Paper": {
        "type": "object",
        "properties": {
          "paper_id": {
            "type": "string",
            "description": "arXiv id or ssrn-<id>."
          },
          "title": {
            "type": "string"
          },
          "paper_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "authors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "topics": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Topic-hub slugs; hub page at https://thequant.space/topics/<slug>/."
          },
          "methods": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Method slugs; hub page at https://thequant.space/methods/<slug>/."
          },
          "asset_classes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Keywords extracted from the abstract."
          },
          "paper_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "primary_category": {
            "type": [
              "string",
              "null"
            ],
            "description": "Primary arXiv category."
          },
          "quadrant": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "Holy Grail",
              "Street Traders",
              "Lab Rats",
              "Philosophers",
              null
            ]
          },
          "math_complexity": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 10
          },
          "empirical_rigor": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 10
          },
          "hub_score": {
            "type": [
              "number",
              "null"
            ],
            "description": "0.6*empirical_rigor + 0.4*math_complexity."
          },
          "code_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "paper_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "The paper (arXiv PDF or SSRN page)."
          },
          "page_url": {
            "type": "string",
            "description": "The paper's page on thequant.space."
          },
          "summary": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "PaperFull": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Paper"
          },
          {
            "type": "object",
            "properties": {
              "abstract": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "rationale": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The written justification for the two scores."
              },
              "flowchart": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Mermaid source of the research flowchart (goal, data, method, computation, findings)."
              },
              "doi": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "journal_ref": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "updated_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "related": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Paper"
                }
              }
            }
          }
        ]
      },
      "PaperList": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "description": "Papers matching the filters."
          },
          "count": {
            "type": "integer",
            "description": "Papers in this page."
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "params": {
            "type": "object",
            "additionalProperties": true,
            "description": "The normalised filters that were applied."
          },
          "next": {
            "type": "string",
            "description": "Relative URL of the next page, when there is one."
          },
          "papers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Paper"
            }
          }
        }
      },
      "Hub": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string"
          },
          "data_url": {
            "type": "string",
            "description": "Per-topic JSON shard (topics only)."
          },
          "count": {
            "type": "integer"
          },
          "rigor7_share": {
            "type": "integer",
            "description": "Percent of papers with empirical_rigor >= 7."
          },
          "with_code": {
            "type": "integer"
          },
          "guides": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Guide slugs (methods only); text via https://thequant.space/guides/<slug>/."
          }
        }
      },
      "HubList": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer"
          },
          "topics": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hub"
            }
          },
          "methods": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hub"
            }
          }
        }
      }
    }
  }
}