Skip to content
superPDF

API quickstart

Start the API and make your first PDF with it in about two minutes.

Everything happens in one Terminal window. You need the superpdf command (see PDF CLI) and a PDF in ~/Documents/superPDF. The examples use report.pdf: change it to the name of one of your files.

1. Start the API

Terminal
export SUPERPDF_API_TOKEN="$(openssl rand -hex 32)"
superpdf serve --allow-dir ~/Documents/superPDF &

The & keeps the API running in the background of this window, so you can go on typing. It prints its address and waits for requests.

2. List your PDFs

Terminal
curl -s http://127.0.0.1:7341/v1/tools/pdf_list_files \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "folder": "/Users/<you>/Documents/superPDF",
  "files": [
    {
      "path": "/Users/<you>/Documents/superPDF/appendix.pdf",
      "bytes": 971,
      "modified": "2026-10-11T01:55:09.735Z"
    },
    {
      "path": "/Users/<you>/Documents/superPDF/report.pdf",
      "bytes": 1805,
      "modified": "2026-10-11T01:55:09.734Z"
    }
  ]
}

3. Run a tool

Copy the first page of report.pdf into a new file:

Terminal
curl -s http://127.0.0.1:7341/v1/tools/pdf_extract_pages \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "input": "report.pdf", "pages": "1", "output": "first-page.pdf" }'
Response
{
  "output": "/Users/<you>/Documents/superPDF/first-page.pdf",
  "pages": 1,
  "bytes": 1003
}

Open it in Preview:

Terminal
open ~/Documents/superPDF/first-page.pdf

4. Stop the API

Terminal
kill %1

Closing the Terminal window stops it too. Each start makes a new token; to keep one for your scripts, see Token lifecycle.

Next

AuthenticationTokens, the Host and Origin checks, and calls from web pages.Calling toolsA typed client in TypeScript, Python or Go, and your first calls.Endpoint referenceEvery endpoint, its fields, limits and a real example.