Guides

Getting Started

Paperpile gives your scripts, integrations and AI agents access to the data in your Paperpile libraries. This page shows the ways in, and how that data is organized.

Ways to work with your library

You want to… Use Start here
Call Paperpile from your own code, in any language The REST API API Reference
Work from a terminal or a shell script The CLI CLI
Let an AI assistant or agent read and edit your library The MCP server MCP and agents

All three accept an API key from your Paperpile account settings. Apps that act on behalf of other people use OAuth 2.0 access tokens instead. Authentication explains both.

How your data is organized 

Libraries        your personal library, plus shared libraries and shared folders
├── References   articles, books, websites, datasets…; the type sets the available fields
│   ├── Files    one primary PDF and any number of supplementary files
│   └── Notes    notes and PDF annotations
├── Folders      a hierarchy; a reference can sit in several folders
└── Labels       flat, colored tags; a reference can carry several labels
  • Libraries hold everything else. You have one personal library; shared libraries and shared folders are the ones you work on with others. API requests and CLI commands act on your personal library unless they name another one.
  • References are the core resource: citable sources such as journal articles, books, conference papers, websites and datasets. Each has a type, which determines its fields, and starred and trashed flags.
  • Folders organize references into a hierarchy, like directories. Removing a reference from a folder, or deleting the folder, does not delete the reference.
  • Labels are colored tags with no hierarchy, suited to themes that cut across folders, such as "To read".
  • Files are documents attached to a reference, usually its PDF. A reference has at most one primary file.
  • Notes are notes and PDF annotations attached to a reference.

Next steps