Raw schema
{
"type": "object",
"properties": {
"pmcids": {
"description": "PMC IDs to fetch (e.g. [\"PMC9575052\"]). Combinable with `pmids` and `dois` โ up to 50 distinct identifiers across the three; the first 10 are fetched per call, the rest returned in `overLimit`. PMC IDs with no retrievable full text fall through to Europe PMC, then to Unpaywall on the DOI the chain resolves for them.",
"minItems": 1,
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"pattern": "^(?:PMC)?\\d+$"
}
},
"pmids": {
"description": "PubMed IDs. Combinable with `pmcids` and `dois` โ up to 50 distinct identifiers across the three; the first 10 are fetched per call, the rest returned in `overLimit`. Articles in PMC are returned as structured JATS; articles not in PMC fall through to Europe PMC (when EPMC has a `fullTextXML`), then to Unpaywall when `UNPAYWALL_EMAIL` is set and a DOI is available.",
"minItems": 1,
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"pattern": "^\\d+$"
}
},
"dois": {
"description": "DOIs to resolve (e.g. [\"10.21203/rs.3.rs-9010375/v1\"]), one per element. Combinable with `pmcids` and `pmids` โ up to 50 distinct identifiers across the three; the first 10 are fetched per call, the rest returned in `overLimit`. Resolved to a PMCID via the PMC ID Converter and returned as structured JATS when the article is in PMC; DOIs with no PMC counterpart (preprints, EPMC-only OA) fall through to Europe PMC, then Unpaywall, when those layers are enabled.",
"minItems": 1,
"maxItems": 50,
"type": "array",
"items": {
"type": "string",
"pattern": "^10\\.[^\\s,]+\\/[^\\s,]+$"
}
},
"includeReferences": {
"default": false,
"description": "Include reference list. Applies to `source=pmc` results only.",
"type": "boolean"
},
"includeTables": {
"default": true,
"description": "Include the article's tables โ cells, captions, labels and footnotes. On by default because a dropped table takes its numbers with it. Table-dense articles pay for it: rendered tables typically add 12โ17% to an article record and can more than double it. Set false to omit them, or cap the cost with `maxCharacters`, which drops tables it cannot fit whole. Applies to `source=pmc` results only.",
"type": "boolean"
},
"includeAssets": {
"default": true,
"description": "Include the article's figures and supplementary material โ `assets[]`, each with its label, caption, enclosing section and deposit pointer. On by default because it is cheaper than tables: a median asset-bearing article grows about 10%, and the body prose already refers to these by label. Set false to omit them, which also removes the `[Figure: โฆ]` / `[Supplementary: โฆ]` markers from the section text, since without the array they point at nothing. Prose-shaped blocks โ lists, definition lists, block quotes, boxed text, preformatted blocks, displayed formulae โ are section text rather than assets and this switch never affects them. Applies to `source=pmc` results only.",
"type": "boolean"
},
"maxSections": {
"description": "Maximum top-level sections, counted after `sections`. Back-matter sections count and follow the body, so a cap drops them first. The sections it drops are named per article in `sectionCap`. Applies to `source=pmc` results only.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"sections": {
"description": "Filter to specific sections by title (e.g. [\"Introduction\", \"Methods\", \"Results\", \"Discussion\"]). A term matches a section or subsection title at any nesting depth, case-insensitively, as a substring โ \"resul\" matches \"Results\". Back-matter sections match the same way: by their own titles, or by their kind when they carry neither a title nor a label โ \"appendix\" matches a section titled \"Appendix A\", \"footnotes\" an untitled footnote group. A label is never matched, so an appendix labelled \"Appendix A\" under a title of its own matches only on that title. A section whose own title matches is returned whole; one kept only because a nested subsection matched keeps its heading as a breadcrumb, with its own text cleared and only the matching branch beneath it. Tables and assets narrow with the filter: one whose section did not survive, or that names no section, is dropped. Empty strings are skipped, so `[\"\"]` applies no filter; an element of only whitespace or invisible characters, such as a zero-width space, is rejected. Applies to `source=pmc` results only.",
"type": "array",
"items": {
"type": "string"
}
},
"maxCharacters": {
"description": "Per-article budget for body text, in characters. Counts `source=pmc` section and subsection text โ which carries the inline blocks the parser renders in place, such as lists, definition lists, block quotes, boxed text, preformatted blocks and displayed formulae โ plus table label, caption, cell and footnote text and asset label, caption and `href` text; or the `source=unpaywall` `content` body. Titles, abstracts, identifiers, licenses, and references are never counted or shortened. Shortened text ends at the last word boundary inside its allowance, so it can come back a few characters under it; a section or subsection whose allowance cannot hold its first word returns no text rather than part of that word, so it is dropped in `truncate` mode and heading-only in `outline` mode, while text that is one unbroken token, such as a sequence or URL, is cut at the allowance. The counted unit is that text alone โ the Markdown grid `content[]` renders around the cells (pipes, padding, the divider row, headings) is scaffolding this budget does not measure, so a table renders longer than it costs here. Body sections are served first, then tables, then assets, then back-matter sections, each spending what is left, in document order. For tables and assets, admission stops at the first entry that does not fit, and every entry from there on is dropped whole rather than cut mid-row or returned with a shortened caption, counted in `truncation.omittedTables` / `truncation.omittedAssets` and named in `truncation.articles[].omittedTableNames` / `omittedAssetNames`. Back matter takes only what remains and is shortened or dropped as body sections are; `sections` still returns it after the body. Applied after `sections`, `maxSections`, `includeReferences`, `includeTables`, and `includeAssets`, so semantic filtering is unaffected. This knob alone bounds only bodies: the response-wide ceiling it implies is this value times the number of articles returned, plus every uncounted field. Use `maxResponseCharacters` for a true whole-response ceiling. Omit for the full body.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"maxCharactersPerSection": {
"description": "Budget for a single top-level section, in characters, counting the section text plus its subsections. Combine with `maxCharacters` to cap both one section and the article; the tighter of the two wins. Applies to `source=pmc` results only.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"maxResponseCharacters": {
"description": "Opt-in ceiling for the whole response, in characters โ the true response-wide counterpart to the per-article `maxCharacters`. Each article is measured as the JSON record it is returned as, after every filter and the per-article body budget: title, abstract, sections, references, identifiers, license and source metadata โ every field it carries. One ledger covers all tiers, so PMC-, Europe PMC-, and Unpaywall-served articles spend the same budget. Articles are kept in the order `articles` lists them until the next one would cross the ceiling; that article and the rest are deferred whole (never partially populated) and listed in `deferred.ids`. Response envelope fields โ counts, `unavailable`, `truncation`, `sectionCap`, `deferred` itself โ are not counted. Omit to return every resolved article.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"overflowMode": {
"default": "truncate",
"description": "How to spend `maxCharacters` across an article that exceeds it. truncate: fill sections in document order, so early sections stay whole, the section the budget runs out in is cut, and every section or subsection past that point is dropped (counted in `truncation.omittedSections`). outline: every section and subsection keeps its heading, and the budget is split evenly at every level โ across the top-level sections, then inside each one across its own text and each subsection โ with what a short part does not need going to the rest. A part whose share would cut it to under 100 characters (or under `maxCharactersPerSection`, when that is lower) returns heading-only instead, its share going to the others, emptying the last such part first; a part that fits its share keeps all its text however short, and a cut excerpt ends at the last word boundary inside its share, so it can run somewhat under that floor. A heading the budget left empty is marked as such in the rendered text. In both modes the body sections spend the budget first and back-matter sections share what the body, tables, and assets leave. Use it to survey what an article contains before requesting specific `sections`. Ignored when no budget is set, and identical for `source=unpaywall` bodies, which have no headings to preserve.",
"type": "string",
"enum": [
"truncate",
"outline"
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}