# hedgefund.wiki Knowledge API

> Institutional-grade hedge fund knowledge as machine-readable JSON. No auth, CC-BY-4.0, and built LLM-first.

The current public API lives under `/api/v1/*`. Generated static artifacts are built from `data/*.json` by `scripts/build.py` and served through Cloudflare Pages Functions in `functions/api/v1/**`.

## TL;DR

| If you want | Fetch this |
|---|---|
| Everything in one file for LLM context ingestion | [`/llms-full.txt`](https://hedgefund.wiki/llms-full.txt) |
| Concise LLM discovery summary | [`/llms.txt`](https://hedgefund.wiki/llms.txt) |
| Endpoint catalog and corpus counts | [`/api/v1/manifest`](https://hedgefund.wiki/api/v1/manifest) |
| OpenAPI 3.1 spec | [`/api/v1/openapi.json`](https://hedgefund.wiki/api/v1/openapi.json) |
| RAG-ready chunks for a vector DB | [`/api/v1/llms/chunks`](https://hedgefund.wiki/api/v1/llms/chunks) |
| A single concept | [`/api/v1/terms/sharpe-ratio`](https://hedgefund.wiki/api/v1/terms/sharpe-ratio) |
| A graph neighborhood | [`/api/v1/graph/sharpe-ratio?depth=2`](https://hedgefund.wiki/api/v1/graph/sharpe-ratio?depth=2) |

## Endpoint Families

### Discovery

- `GET /api/v1/health` — service health and API version header.
- `GET /api/v1/manifest` — master index of endpoints, schemas, and corpus counts. Read this first.
- `GET /api/v1/stats` — generated corpus counts and build metadata.
- `GET /api/v1/openapi.json` — OpenAPI 3.1 contract.
- `GET /llms.txt` — concise overview for agents.
- `GET /llms-full.txt` — aggregated reference for one-shot LLM ingestion.
- `GET /sitemap.xml` — XML sitemap for crawlers.
- `GET /.well-known/ai-plugin.json` — ChatGPT plugin manifest.

### Knowledge

- `GET /api/v1/terms` — 1,074 terms with pagination, category filtering, search, and field projection.
- `GET /api/v1/terms/{slug}` — canonical term payload with optional backlinks and graph context.
- `POST /api/v1/terms/_bulk` — up to 200 term lookups with optional `fields` projection.
- `GET /api/v1/terms/_random?n=3` — random term sampling.
- `GET /api/v1/categories` and `GET /api/v1/categories/{slug}` — 20 knowledge domains.
- `GET /api/v1/strategies` and `GET /api/v1/strategies/{slug}` — 12 hedge fund strategy profiles.
- `GET /api/v1/regulations` and `GET /api/v1/regulations/{slug}` — 14 regulatory frameworks.
- `GET /api/v1/calculators` and `GET /api/v1/calculators/{slug}` — 20 calculator definitions.
- `GET /api/v1/conventions` and `GET /api/v1/conventions/{slug}` — day-count, settlement, business-day, and compounding conventions.
- `GET /api/v1/sources` and `GET /api/v1/sources/{id}` — bibliographic source registry.
- `GET /api/v1/people` and `GET /api/v1/people/{slug}` — manager and market participant profiles.

### Graph, Search, And Compute

- `GET /api/v1/search?q={query}` — full-text search across terms, strategies, regulations, and calculators.
- `GET /api/v1/graph/{slug}?depth=1|2` — term graph neighborhood with nodes and edges.
- `GET /api/v1/llms/chunks?kind=term|strategy|regulation|calculator` — pre-chunked NDJSON or JSON corpus.
- `GET|POST /api/v1/compute/{slug}` — executable calculators such as `sharpe-ratio`, `black-scholes`, `var-parametric`, `kelly-criterion`, and `beta-capm`.

## Request Conventions

- **IDs**: stable kebab-case slugs, e.g. `sharpe-ratio`, `long-short-equity`.
- **Formats**: use `?format=json|ndjson|jsonld|md` or an `Accept` header.
- **Projection**: list endpoints support `fields=slug,term` where route code implements projection.
- **Pagination**: list endpoints use `limit` and `offset`.
- **Encoding**: UTF-8 throughout.
- **Null policy**: missing fields are omitted where possible instead of returned as `null`.
- **Errors**: failures return RFC 7807 `application/problem+json`.
- **Caching**: successful responses include `ETag`; send `If-None-Match` for `304` responses.
- **CORS**: all API responses allow `Access-Control-Allow-Origin: *`.

## Local Development And Tests

```bash
# Regenerate generated API artifacts
python3 scripts/build.py

# Deterministic build timestamp for reproducible review
BUILD_TIME=2026-05-03T00:00:00+00:00 python3 scripts/build.py

# Calculator math tests
node scripts/test_finmath.mjs

# Cloudflare Pages Function harness
node scripts/test_server.mjs
```

`scripts/test_server.mjs` invokes Pages Function modules directly and binds `env.ASSETS.fetch` to a local filesystem reader. It auto-runs `scripts/build.py` only when `api-build/v1/manifest.json` is missing; rebuild manually when source data has changed and local artifacts already exist.

For the full architecture, diagrams, troubleshooting matrix, and future remediation plan, see [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md).

## License

All public data and prose are released under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/). Attribution: `hedgefund.wiki`.

## Contact

`api@hedgefund.wiki`