JNIS local API explorer

Start here

A short, offline tour of the read-only search, metadata, full-text, and MCP interfaces. This page works from the downloaded archive: no Node, key, JavaScript, CDN, or network is needed.

All examples are synthetic. The identifiers, titles, authors, DOI-like strings, XML, JSON, Markdown, and observations below are invented interface illustrations. They are not JNIS content, clinical evidence, or recorded API responses.

Download the key-free demo ZIP · Read the dev API documentation

Dev contains 100 JNIS articles from publisher JATS. The download opens immediately with this guide; its optional local explorer can run all examples against dev after you supply your own JNIS customer key.

The interface in one minute

Terms / BM25

Search words and quoted phrases. A name and year are ordinary query text.

Bibliographic author + year

Use search_mode=bibliographic when you mean an author and publication-year lookup.

Metadata and full delivery

Use thin candidates for ranking, frontmatter for metadata, then JATS, canonical JSON, or Markdown for one article.

MCP

search returns compact hits and abstracts; fetch retrieves one complete article. Vector and hybrid ranking are reserved, not active.

Search modes

Terms mode treats words as search text. Bibliographic mode applies metadata filters and returns the interpretation.

Terms, spelling, and phrases

GET /v1/articles?collection_id=jnis-100&query=ischaemic+stroke&search_mode=terms&include=frontmatter
GET /v1/articles?query=ischemic+stroke&search_mode=terms
GET /v1/articles?query=%22flow+diverter%22&search_mode=terms

{"hits":[{"id":"illustrative-a","title":"Illustrative stroke article"}],
 "total":1,"returned":1,"query":{"strategy":"any_term_or_phrase"}}

UK/US spelling exercises lexical normalization. Quotation marks keep a phrase together. Exact rankings depend on the authorised corpus.

Bibliographic author and year

GET /v1/articles?collection_id=jnis-100&query=Example+2025&search_mode=bibliographic&include=frontmatter
{"hits":[{"id":"illustrative-a","title":"Illustrative stroke article",
          "abstract":"Synthetic abstract for the walkthrough."}],
 "query":{"strategy":"bibliographic",
  "interpretation":{"status":"applied","author":"Example",
                   "year":2025,"date_basis":"any"}}}

Thin candidates, metadata, and full text

Need	Operation	Shape
Rank quickly	`GET /v1/articles` without `include`	`hits` with identifiers and titles; no copied abstracts.
Complete metadata	`GET /v1/frontmatter?ids=...`	`items` with abstracts, authors, keywords, DOI, journal, licence, dates, and version metadata.
One article	`GET /v1/articles/{id}?format=...`	Full JATS XML, canonical JSON, or Markdown with references.

Batch frontmatter preserves requested order

GET /v1/frontmatter?ids=illustrative-b,illustrative-a&collection_id=jnis-100
{"items":[
 {"id":"illustrative-b","title":"Illustrative stroke article",
  "authors":["Avery Example"],"abstract":"Synthetic abstract...",
  "doi":"10.0000/illustrative-article-b"},
 {"id":"illustrative-a","title":"Illustrative flow diverter article",
  "authors":["Avery Example"],"abstract":"Synthetic abstract...",
  "doi":"10.0000/illustrative-article-a"}],
 "returned":2,"next_cursor":null}

The current interface allows up to 300 candidates per page and 50 metadata identifiers per batch. Final MCP hit limits and request quotas come from the customer's policy.

Three full formats

GET /v1/articles/illustrative-a?format=jats
<article><article-title>Illustrative article — not publisher content</article-title>...</article>

GET /v1/articles/illustrative-a?format=json
{"article":{"schema_version":"bmj-content/1","blocks":[{"kind":"paragraph","text":"Example content only."}],"references":[{"id":"ref1","text":"Synthetic reference."}]}}

GET /v1/articles/illustrative-a?format=markdown
# Illustrative article

Example content only.

## References
Example reference (synthetic).

MCP for agents

MCP uses JSON-RPC over /mcp. Search is compact and fetch is complete; both are read-only and scoped to the authorised customer.

MCP search

POST /mcp
{"jsonrpc":"2.0","id":"demo-1","method":"tools/call",
 "params":{"name":"search","arguments":{"query":"Example 2025"}}}

{"jsonrpc":"2.0","id":"demo-1","result":{"structuredContent":{
 "results":[{"id":"illustrative-a","title":"Illustrative article",
             "url":"https://example.invalid/illustrative-article"}],
 "interpretation":{"status":"applied","author":"Example","year":2025}}}}

MCP fetch

POST /mcp
{"jsonrpc":"2.0","id":"demo-2","method":"tools/call",
 "params":{"name":"fetch","arguments":{"id":"illustrative-a"}}}

{"jsonrpc":"2.0","id":"demo-2","result":{"structuredContent":{
 "id":"illustrative-a","title":"Illustrative article",
 "text":"# Illustrative article\n\nExample content only.\n\n## References\n...",
 "metadata":{"authors":["Avery Example"]}}}}

Two deliberate outcomes

An ambiguous name-like query in auto mode can return clarification_required. Zero displayed hits then means “choose a mode”, not “no paper exists”.
rank=vector or rank=hybrid returns explicit HTTP 501 for this JATS profile. Vectors are reserved and inactive; the demo makes no model calls.

Expected vector capability response

HTTP/1.1 501 Not Implemented
{"ok":false,"code":"rank_unavailable",
 "error":"This collection currently supports rank=bm25 only."}

Try the local demo

For the key-free tour, run node server.mjs --offline from this folder.
Open http://127.0.0.1:4317 and start on Guided tour.
Use “Try in explorer” on a scenario and expand its exact request and response.
For live development calls, run node server.mjs --ask-key with Node.js 22 or later. Paste your separately issued JNIS customer key into the hidden terminal prompt, then choose Run all against dev. The key stays server-side; never add it to this archive.

Live credentials and licensed responses stay with the authorised local environment.

This walkthrough is intentionally synthetic. It teaches request and response shapes without reproducing actual articles or claiming an example was measured against JNIS.