References

References are the core resource in your library. They represent citable sources like journal articles, books, conference papers, websites, datasets, and more.

Each reference has a type field (e.g., article, book, website) that determines its available fields. Common fields like title, author, and doi appear across most types, while others are type-specific (e.g., journal for articles, isbn for books).

Beyond bibliographic data, references include organizational metadata folders, labels, starred, and trashed flags—as well as associated files (PDFs).

To create a reference, only type and title are required. Updates accept any mutable field but must include at least one; the type of an existing reference cannot be changed.

To add several references at once, POST /references/save accepts any combination of dois (resolved against Paperpile's metadata service), a bibtex document, and complete references objects — up to 50 per source. Results are grouped by source and reported per entry: dois keyed by DOI, bibtex by citation key, and references in the same order as the entries you sent, each created, duplicate, or failed. labels, folders, and note given on the request apply to everything saved, in addition to anything already set on an individual entry. An entry already in your library is reported as duplicate rather than inserted; pass skipDuplicates=false to always insert. A request must carry at least one of dois, bibtex, or references.

A request-level note is appended to whatever note the entry already carries — a BibTeX note field or a note on a supplied reference object is never overwritten.

References created through POST /references and POST /references/save are marked for a PDF crawl: the next time your Paperpile browser extension syncs, it looks for each new reference's full-text PDF and attaches it. Pass findPdfs=false to skip that. The crawl runs after the response is sent and its result is not reported here — it needs a signed-in extension to be running, and not every reference has a reachable PDF. Poll GET /references/{id}/files to see whether one arrived.

A DOI the metadata service has no record for fails with doi_not_resolved, while a DOI whose lookup could not be completed — the service was unreachable or returned an error — fails with reference_lookup_failed, so a transient outage is distinguishable from a DOI that genuinely has no match and is worth retrying.

Identifier and date fields are validated on both create and update, matching the Paperpile app. Identifiers must be well-formed — for example, doi like 10.1000/xyz123, pmid as 6 to 8 digits, pmc like PMC1234567, and isbn a valid ISBN-10 or ISBN-13; other identifiers (arxivid, ismn, zbl, mr, lccn) must match their standard formats. Date fields (published, accessed, originally_published, conference_date, filed) accept a partial date YYYY, YYYY-MM, or YYYY-MM-DD, with month 01 to 12, day 01 to 31, and year 2030 or earlier. Invalid values are rejected with a 400 validation_error rather than being silently dropped; each field's description states its specific rule.

Fields are also checked against the reference's type: a field that doesn't apply to the type (for example booktitle on an article) is rejected with a 400 rather than silently ignored. Each type's valid fields are those shown in its schema below.

The reference lists — GET /references and the folder- and label-scoped variants (/folders/{folder_id}/references, /labels/{label_id}/references) — are the only cursor-paginated lists in this API. Use limit (1–100, default 50) together with the cursor from the previous response to page through results; cursor is null on the final page. Use expand (folders, labels) to inflate ID arrays into full objects, and fields to limit the returned columns.

Bulk operations (PATCH /references/bulk, DELETE /references/bulk) return 200 with { "succeeded": <count> }.

To work in a shared library instead of your personal library, see Resource and endpoint conventions.

See the Reference object for the full schema.