API Docs

Base

All endpoints are relative to your deployment origin. See /api/health for a quick status snapshot.

GET  /api/health
POST /api/format
POST /api/format/stream   (NDJSON)
POST /api/format-items
POST /api/export

/api/format

Formats a list of identifiers (DOI / PMID / PMCID / ISBN / WHO IRIS). Detects & normalizes.

POST /api/format
Content-Type: application/json

{
  "text": "10.1038/nphys1170\nPMID: 34812345\n9780306406157",
  "style": "vancouver",          // or "ama" | "apa" | "ieee" | any CSL style id (e.g., "chicago-author-date")
  "locale": "en-US",              // optional CSL locale (e.g., "en-GB")
  "output": "text",               // "text" | "html" (CSL)
  "footnotes": false              // when output=html, render as footnotes
}

200 OK
X-Scholar-Cache: ENABLED|BYPASS
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 28
X-RateLimit-Reset: 1736569200

{
  "ok": true,
  "items": [
    { "ok": true, "formatted": "Doe J, ..." , "_source": { "id": "10.1038/nphys1170", "fetchedAt": "..." } },
    { "ok": false, "error": "PMID not found" }
  ]
}

curl -sS -X POST "$ORIGIN/api/format" \
  -H "Content-Type: application/json" \
  -d '{"text":"10.1038/nphys1170","style":"vancouver","output":"text"}'

/api/format/stream (NDJSON)

Streams events: start → item → done.

curl -N -sS -X POST "$ORIGIN/api/format/stream" \
  -H "Content-Type: application/json" \
  -d '{"text":"10.1038/nphys1170\nPMID:34812345","style":"apa","output":"html"}'

/api/format-items

Like /api/format but accepts already-resolved CSL JSON items.

/api/export

Exports to TXT, BibTeX, RIS, CSL JSON, EndNote (Refer/XML), RefWorks, MEDLINE, CSV, Zotero RDF.

curl -sS -X POST "$ORIGIN/api/export" \
  -H "Content-Type: application/json" \
  -d '{"text":"10.1038/nphys1170\n9780306406157","format":"ris","style":"vancouver"}' \
  -o citations.ris

Headers & Limits

• X-Scholar-Cache: BYPASS or ENABLED
• Rate limiting: X-RateLimit-* + Retry-After (HTTP 429 on excess).
• Content types: JSON for API responses; streamed NDJSON on /api/format/stream; exporter returns appropriate Content-Type + Content-Disposition.