No code? Use /app — paste your key and search from the browser. Base URL https://codeblack-api.dajai.io. Every request except /v1/health and billing needs Authorization: Bearer cbk_live_…. JSON in, JSON out. Errors are {"error": "…"} with a proper status.
| Endpoint | Units |
|---|---|
me | 0 |
person | 1 |
persons | 1 |
lineage | 5 |
records | 3 |
text | 2 |
semantic | 10 |
bridge | 10 |
gaps | 2 |
gedcom | 25 |
start | 1 |
wall | 3 |
| Method · path | Params | Returns |
|---|---|---|
GET /v1/health | — | engine + service health (public) |
GET /v1/me | — | your plan, month-to-date units, overage, by-endpoint usage |
GET /v1/persons | q, lineage, limit | persons (name search) |
GET /v1/persons/:id | — | person + claims (with source title/url) + relationships + variants + findings |
GET /v1/lineage/:id | max_gen | recursive ancestor walk, deepest on spine, deepest collateral |
GET /v1/records/search | q, tables (csv of ds_* names), limit | hits per table |
GET /v1/text/search | q, limit | research text chunks |
POST /v1/semantic | JSON {q, k, pools:["rec","text","name"]} | cosine-ranked records / chunks / names |
POST /v1/bridge/run | JSON {name, birth_year?, place?, holder?, k?} | ranked record leads for your ancestor + exact hits |
GET /v1/gaps | — | engine gap report |
GET /v1/export/gedcom | subject?, lineage?, raw=1 for text/plain | GEDCOM 5.5.1 public export (no living persons); needs your key |
POST /v1/billing/checkout | plan, email (form or JSON) | Stripe Checkout url (303 redirect for forms) |
GET /claim?session_id= | — | shows your key once after checkout |
curl -s https://codeblack-api.dajai.io/v1/bridge/run -H "Authorization: Bearer $CODEBLACK_KEY" -H "Content-Type: application/json" \
-d '{"name":"Gilbert Handy","birth_year":1825,"place":"St. Landry Parish, Louisiana"}'
Streamable HTTP at POST /mcp (JSON-RPC 2.0, stateless). Tools: cb_person, cb_persons_search, cb_lineage, cb_records_search, cb_text_search, cb_semantic_search, cb_bridge_run, cb_gaps, cb_export_gedcom, cb_start, cb_wall.
claude mcp add --transport http codeblack https://codeblack-api.dajai.io/mcp --header "Authorization: Bearer $CODEBLACK_KEY"
{"mcpServers":{"codeblack":{"type":"http","url":"https://codeblack-api.dajai.io/mcp","headers":{"Authorization":"Bearer cbk_live_…"}}}}
Per-plan calls per minute and units per day (see pricing). 429 when exceeded. Keys are revoked automatically when the subscription ends.
Every person, claim and edge carries the engine's confidence verbatim and a mapped tier: RECORD (a cited document) · TRIANGULATED (converging records) · TESTIMONY (first-hand family knowledge, primary evidence) · COMPILED (a compiled tree, not a document) · HYPOTHESIS · WITHDRAWN. The GEDCOM maps these to QUAY 3/2/1/0. Nothing is promoted; nothing is invented.