Connect products and agents to BMJ content through one stable contract.

Find: lexical search, article level

POST /v1/find with level: "article" runs D1 FTS5 BM25 over titles and abstracts. Quote a phrase for an exact match. Fast (100–300 ms) and does not touch the retrieval/generation stack.

curl -X POST 'https://dev.bmj-content-hub.com/v1/find' \
  -H "Authorization: Bearer ${BMJ_EVIDENCE_API_KEY}" \
  -H 'Content-Type: application/json' \
  -H 'X-Request-Id: client-generated-unique-id' \
  --data '{
    "query": "\"treatment adherence\"",
    "level": "article",
    "limit": 10
  }'

{
  "ok": true,
  "request_id": "req_...",
  "level": "article",
  "query": "\"treatment adherence\"",
  "hits": [
    { "document_id": "doc_...", "title": "...", "snippet": "...<b>treatment adherence</b>...", "score": 4.9, "journal_id": "bmjonc", "published_at": "2026-03-01", "doi": "10...." }
  ],
  "total": 12,
  "next_cursor": 10,
  "timings_ms": { "fts": 42, "total": 61 }
}

Search: keyword, vector, hybrid

POST /v1/search retrieves ranked evidence previews. retrieval selects keyword (D1 FTS5), vector (Workers AI query embedding against Vectorize) or hybrid (both, fused by reciprocal rank). An optional backend field overrides the gateway/AI-Search stack per request; results are memoised 5 minutes per query, scope and release.

curl -X POST 'https://dev.bmj-content-hub.com/v1/search' \
  -H "Authorization: Bearer ${BMJ_EVIDENCE_API_KEY}" \
  -H 'Content-Type: application/json' \
  -H 'X-Request-Id: client-generated-unique-id' \
  --data '{
    "query": "What evidence discusses treatment adherence?",
    "max_results": 5,
    "retrieval": "keyword"
  }'

curl -X POST 'https://dev.bmj-content-hub.com/v1/search' \
  -H "Authorization: Bearer ${BMJ_EVIDENCE_API_KEY}" \
  -H 'Content-Type: application/json' \
  -H 'X-Request-Id: client-generated-unique-id' \
  --data '{
    "query": "What evidence discusses treatment adherence?",
    "max_results": 5,
    "retrieval": "vector"
  }'

curl -X POST 'https://dev.bmj-content-hub.com/v1/search' \
  -H "Authorization: Bearer ${BMJ_EVIDENCE_API_KEY}" \
  -H 'Content-Type: application/json' \
  -H 'X-Request-Id: client-generated-unique-id' \
  --data '{
    "query": "What evidence discusses treatment adherence?",
    "max_results": 5,
    "retrieval": "hybrid",
    "rerank": true
  }'

Answers: JSON

POST /v1/answers retrieves, assembles bounded evidence context, generates with Workers AI and verifies citations. Requires the answer:generate capability and scope, a preview-or-higher content grant, and evidence inside the agreement collections. Empty retrieval returns HTTP 404 no_evidence rather than an empty or hallucinated answer.

curl -X POST 'https://dev.bmj-content-hub.com/v1/answers' \
  -H "Authorization: Bearer ${BMJ_EVIDENCE_API_KEY}" \
  -H 'Content-Type: application/json' \
  -H 'X-Request-Id: client-generated-unique-id' \
  --data '{"query":"What does the evidence say about treatment adherence?"}'

{
  "ok": true,
  "request_id": "req_...",
  "answer": "Evidence suggests ... [E1].",
  "grounding": { "valid": true, "warnings": [] },
  "sources": [ { "evidence_id": "para_...", "score": 0.81, "text": "..." } ],
  "execution_context": { "retrieval": "hybrid", "generator_model": "@cf/zai-org/glm-4.7-flash", "generator_provider": "cloudflare-workers-ai" },
  "usage": { "answer_requests": 1, "model_1k_tokens": 2 },
  "timings_ms": { "retrieval": 210, "generation": 2480, "total": 2810 }
}

tools/list

Discover the tools available to the authenticated customer before calling one.

curl -X POST 'https://dev.bmj-content-hub.com/mcp' \
  -H "Authorization: Bearer ${BMJ_EVIDENCE_API_KEY}" \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  --data '{
    "jsonrpc": "2.0",
    "id": "tools-1",
    "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": {
          "name": "BMJ quick-start",
          "version": "1.0.0"
        },
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

Chunks: canonical source text

GET /v1/chunks/:evidence_id returns a stable BMJ paragraph or evidence-unit chunk, gated by the chunk content-grant level and source:chunk:read on plan and key. Accepts a para_… id from find_passages/search results or an ev_… evidence-unit id.

curl 'https://dev.bmj-content-hub.com/v1/chunks/para_0123456789abcdef01234567' \
  -H "Authorization: Bearer ${BMJ_EVIDENCE_API_KEY}"

{
  "ok": true,
  "request_id": "req_...",
  "chunk": { "evidence_id": "para_...", "text": "...", "locator": { "kind": "paragraph", "ordinal": 4 }, "citation": { "doi": "10....", "journal_id": "bmjonc" }, "token_count": 210 },
  "usage": { "licensed_content_1k_tokens": 1 }
}

Discover the permitted corpus

GET /v1/customer/corpus-summary reports scoped content-type, journal, date, document, evidence and topic coverage. GET /v1/documents browses only documents admitted to the customer's release and contract scope.

curl 'https://dev.bmj-content-hub.com/v1/customer/corpus-summary' \
  -H "Authorization: Bearer ${BMJ_EVIDENCE_API_KEY}"

curl 'https://dev.bmj-content-hub.com/v1/documents?journal_id=bmjonc&limit=25' \
  -H "Authorization: Bearer ${BMJ_EVIDENCE_API_KEY}"

Inspect article quality signals

The BMJ Article Trust Profile v1 combines versioned journal defaults with article overrides. Every assertion is typed and carries evidence, provenance and an explicit inherited flag. The schema and marker registry are public and require no key.

curl 'https://dev.bmj-content-hub.com/v1/trust/schema'
curl 'https://dev.bmj-content-hub.com/v1/trust/markers'
curl 'https://dev.bmj-content-hub.com/v1/trust/articles/doc_example'

curl 'https://dev.bmj-content-hub.com/v1/articles/doc_example/trust' \
  -H "Authorization: Bearer ${BMJ_EVIDENCE_API_KEY}"