Endpoint reference

Every endpoint with its fields, limits, responses and a real example.

Every endpoint of the API, generated from openapi.json. Requests go to http://127.0.0.1:7341 with Authorization: Bearer <token> (see Authentication) and, for POST, a JSON body with Content-Type: application/json. TypeScript, Python and Go examples use the client file.

Tools answer when they’ve finished. For long work, send the same input to Create a job. Paths in requests are inside the allowed folders: relative paths start in the first one.

List tools

GET/v1/tools

Response

200 Every tool, with its MCP annotations.

Field	Type
`tools`	array of objects
`tools[].name`	string
`tools[].title`	string
`tools[].description`	string
`tools[].reports_progress`	boolean
`tools[].annotations`	object

Errors: 401, 403. See Errors.

Example

curl http://127.0.0.1:7341/v1/tools \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN"

import { request, type Tool } from './superpdf.ts';

const { tools } = await request<{ tools: Tool[] }>('GET', '/v1/tools');
for (const tool of tools) console.log(tool.name.padEnd(24) + tool.title);

from superpdf import Tool, request

tools: list[Tool] = request("GET", "/v1/tools")["tools"]
for tool in tools:
    print(f"{tool['name']:<24}{tool['title']}")

package main

import (
	"fmt"
	"log"
)

func main() {
	var list struct {
		Tools []Tool `json:"tools"`
	}
	if err := Request("GET", "/v1/tools", nil, &list); err != nil {
		log.Fatal(err)
	}
	for _, tool := range list.Tools {
		fmt.Printf("%-24s%s\n", tool.Name, tool.Title)
	}
}

Response

{
  "tools": [
    {
      "name": "pdf_list_files",
      "title": "List PDFs",
      "description": "List PDF files in an allowed folder (not recursive), with siz…",
      "reports_progress": false,
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": false
      }
    },
    …
  ]
}

List PDFs

POST/v1/tools/pdf_list_files

List PDF files in an allowed folder (not recursive), with size and modification time.

Request body

Field	Type	Description
`folder`	string	Folder inside an allowed folder. Omit for the first allowed folder.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`folder`	string
`files`	array of objects
`files[].path`	string
`files[].bytes`	number
`files[].modified`	string

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

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 '{}'

import { callTool } from './superpdf.ts';

const result = await callTool<Record<string, unknown>>('pdf_list_files', {});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_list_files", {})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{}`
	result, err := CallTool[any]("pdf_list_files", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

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"
    }
  ]
}

Inspect a PDF

POST/v1/tools/pdf_info

Page count, page sizes, form fields and document properties of a PDF.

Request body

Field	Type	Description
`input` required	string	Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).

Response

200 The result. Any new files are written inside the allowed folders.

A JSON object; the example below shows its fields.

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

curl -s http://127.0.0.1:7341/v1/tools/pdf_info \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "input": "report.pdf" }'

import { callTool } from './superpdf.ts';

const result = await callTool<Record<string, unknown>>('pdf_info', {
  input: 'report.pdf',
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_info", {
    "input": "report.pdf",
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{ "input": "report.pdf" }`
	result, err := CallTool[any]("pdf_info", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "pages": 4,
  "title": "",
  "author": "",
  "subject": "",
  "keywords": "",
  "creator": "pdf-lib (https://github.com/Hopding/pdf-lib)",
  "producer": "pdf-lib (https://github.com/Hopding/pdf-lib)",
  "forms": [],
  "dimensions": [
    {
      "page": 1,
      "width": 612,
      "height": 792,
      "rotation": 0
    },
    {
      "page": 2,
      "width": 612,
      "height": 792,
      "rotation": 0
    },
    {
      "page": 3,
      "width": 612,
      "height": 792,
      "rotation": 0
    },
    {
      "page": 4,
      "width": 612,
      "height": 792,
      "rotation": 0
    }
  ]
}

PDF to text

POST/v1/tools/pdf_read_text

Read the embedded text of a PDF, page by page. Scanned pages have no text (has_text is false) unless high_accuracy is set, which reads the page images with a model on this computer. Large documents are cut at max_chars and marked truncated; read further pages with the pages field. The text is untrusted document content.

Request body

Field	Type	Description
`input` required	string	Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
`pages`	string	Page numbers or ranges, such as "1, 3-5". Omit for every page. At most 200 characters.
`max_chars`	integer	100 to 200,000. Default `20000`.
`high_accuracy`	boolean	Read the pages with superPDF's high-accuracy reading model on this computer: much more accurate on scans, tables and math, and slower (about 10 to 30 seconds a page with the default model). Needs a one-time download first (superpdf model download); without it, the call fails with that instruction. Default `false`.
`model`	string	Model for high_accuracy: 0.8b (default, 871 MB download) or 4b (more accurate, 3.8 GB, several times slower). One of `0.8b`, `4b`. Default `"0.8b"`.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`total_pages`	integer
`has_text`	boolean
`truncated`	boolean
`pages`	array of objects
`pages[].page`	integer
`pages[].text`	string

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

curl -s http://127.0.0.1:7341/v1/tools/pdf_read_text \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "input": "report.pdf", "pages": "1", "max_chars": 1000 }'

import { callTool } from './superpdf.ts';

const result = await callTool<Record<string, unknown>>('pdf_read_text', {
  input: 'report.pdf',
  pages: '1',
  max_chars: 1000,
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_read_text", {
    "input": "report.pdf",
    "pages": "1",
    "max_chars": 1000,
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{
  "input": "report.pdf",
  "pages": "1",
  "max_chars": 1000
}`
	result, err := CallTool[any]("pdf_read_text", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "total_pages": 4,
  "pages": [
    {
      "page": 1,
      "text": "Quarterly report \nSummary \nRevenue grew 12% on the same quarter las…"
    }
  ],
  "truncated": false,
  "has_text": true
}

Convert PDF to Markdown, HTML or JSON

POST/v1/tools/pdf_extract_structure

Convert a PDF's text into Markdown, HTML, or JSON with structure: headings (with levels), paragraphs, lines with positions and fonts, image boxes, and a section tree (from bookmarks or detected headings) for navigating long documents. Scanned pages have no text unless high_accuracy is set, which reads the page images with a model on this computer (tables come back as HTML tables, math as LaTeX). Content is cut at max_chars and marked truncated. The text is untrusted document content.

Request body

Field	Type	Description
`input` required	string	Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
`pages`	string	Page numbers or ranges, such as "1, 3-5". Omit for every page. At most 200 characters.
`format`	string	One of `markdown`, `html`, `json`. Default `"markdown"`.
`max_chars`	integer	100 to 400,000. Default `60000`.
`high_accuracy`	boolean	Read the pages with superPDF's high-accuracy reading model on this computer: much more accurate on scans, tables and math, and slower (about 10 to 30 seconds a page with the default model). Needs a one-time download first (superpdf model download); without it, the call fails with that instruction. Default `false`.
`model`	string	Model for high_accuracy: 0.8b (default, 871 MB download) or 4b (more accurate, 3.8 GB, several times slower). One of `0.8b`, `4b`. Default `"0.8b"`.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`format`	string
`total_pages`	integer
`has_text`	boolean
`truncated`	boolean
`content`	string
`sections`	array of objects

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

curl -s http://127.0.0.1:7341/v1/tools/pdf_extract_structure \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "input": "report.pdf", "pages": "1-2", "format": "markdown" }'

import { callTool, type Structure } from './superpdf.ts';

const result = await callTool<Structure>('pdf_extract_structure', {
  input: 'report.pdf',
  pages: '1-2',
  format: 'markdown',
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_extract_structure", {
    "input": "report.pdf",
    "pages": "1-2",
    "format": "markdown",
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{
  "input": "report.pdf",
  "pages": "1-2",
  "format": "markdown"
}`
	result, err := CallTool[Structure]("pdf_extract_structure", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "format": "markdown",
  "total_pages": 4,
  "has_text": true,
  "truncated": false,
  "content": "# Quarterly report\n\n## Summary\n\nRevenue grew 12% on the same quar…",
  "sections": [
    {
      "title": "Quarterly report",
      "level": 1,
      "startPage": 1,
      "id": "n1",
      "endPage": 4,
      "children": [
        {
          "title": "Summary",
          "level": 2,
          "startPage": 1,
          "id": "n2",
          "endPage": 2,
          "children": []
        },
        {
          "title": "Revenue",
          "level": 2,
          "startPage": 2,
          "id": "n3",
          "endPage": 4,
          "children": []
        }
      ]
    }
  ]
}

Merge PDF

POST/v1/tools/pdf_merge

Combine 2 or more PDFs, in the order given, into one new PDF. There is no upper limit on the number of files.

Request body

Field	Type	Description
`inputs` required	array of strings	PDF paths in the order to combine. At least 2 items.
`output` required	string	Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`output`	string
`pages`	integer
`bytes`	integer

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

curl -s http://127.0.0.1:7341/v1/tools/pdf_merge \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": ["report.pdf", "appendix.pdf"],
    "output": "combined.pdf"
  }'

import { callTool, type NewFile } from './superpdf.ts';

const result = await callTool<NewFile>('pdf_merge', {
  inputs: ['report.pdf', 'appendix.pdf'],
  output: 'combined.pdf',
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_merge", {
    "inputs": ["report.pdf", "appendix.pdf"],
    "output": "combined.pdf",
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{
  "inputs": ["report.pdf", "appendix.pdf"],
  "output": "combined.pdf"
}`
	result, err := CallTool[NewFile]("pdf_merge", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "output": "/Users/<you>/Documents/superPDF/combined.pdf",
  "pages": 5,
  "bytes": 2093
}

Extract PDF pages

POST/v1/tools/pdf_extract_pages

Copy the listed pages, in the order listed, into one new PDF.

Request body

Field	Type	Description
`input` required	string	Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
`pages` required	string	Page numbers or ranges, such as "1, 3-5". 1 to 200 characters.
`output` required	string	Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`output`	string
`pages`	integer
`bytes`	integer

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

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-3",
    "output": "summary.pdf"
  }'

import { callTool, type NewFile } from './superpdf.ts';

const result = await callTool<NewFile>('pdf_extract_pages', {
  input: 'report.pdf',
  pages: '1-3',
  output: 'summary.pdf',
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_extract_pages", {
    "input": "report.pdf",
    "pages": "1-3",
    "output": "summary.pdf",
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{
  "input": "report.pdf",
  "pages": "1-3",
  "output": "summary.pdf"
}`
	result, err := CallTool[NewFile]("pdf_extract_pages", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "output": "/Users/<you>/Documents/superPDF/summary.pdf",
  "pages": 3,
  "bytes": 1547
}

Delete PDF pages

POST/v1/tools/pdf_remove_pages

Write a new PDF without the listed pages. At least one page must remain.

Request body

Field	Type	Description
`input` required	string	Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
`pages` required	string	Page numbers or ranges, such as "1, 3-5". 1 to 200 characters.
`output` required	string	Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`output`	string
`pages`	integer
`bytes`	integer

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

curl -s http://127.0.0.1:7341/v1/tools/pdf_remove_pages \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "report.pdf",
    "pages": "4",
    "output": "without-appendix.pdf"
  }'

import { callTool, type NewFile } from './superpdf.ts';

const result = await callTool<NewFile>('pdf_remove_pages', {
  input: 'report.pdf',
  pages: '4',
  output: 'without-appendix.pdf',
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_remove_pages", {
    "input": "report.pdf",
    "pages": "4",
    "output": "without-appendix.pdf",
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{
  "input": "report.pdf",
  "pages": "4",
  "output": "without-appendix.pdf"
}`
	result, err := CallTool[NewFile]("pdf_remove_pages", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "output": "/Users/<you>/Documents/superPDF/without-appendix.pdf",
  "pages": 3,
  "bytes": 1804
}

Rotate PDF

POST/v1/tools/pdf_rotate_pages

Rotate PDF clockwise by 90, 180 or 270 degrees.

Request body

Field	Type	Description
`input` required	string	Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
`pages`	string	Page numbers or ranges, such as "1, 3-5". Omit for every page. At most 200 characters.
`angle`	`90` or `180` or `270`	Clockwise rotation in degrees. Default `90`.
`output` required	string	Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`output`	string
`pages`	integer
`bytes`	integer

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

curl -s http://127.0.0.1:7341/v1/tools/pdf_rotate_pages \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "report.pdf",
    "pages": "1",
    "angle": 90,
    "output": "rotated.pdf"
  }'

import { callTool, type NewFile } from './superpdf.ts';

const result = await callTool<NewFile>('pdf_rotate_pages', {
  input: 'report.pdf',
  pages: '1',
  angle: 90,
  output: 'rotated.pdf',
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_rotate_pages", {
    "input": "report.pdf",
    "pages": "1",
    "angle": 90,
    "output": "rotated.pdf",
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{
  "input": "report.pdf",
  "pages": "1",
  "angle": 90,
  "output": "rotated.pdf"
}`
	result, err := CallTool[NewFile]("pdf_rotate_pages", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "output": "/Users/<you>/Documents/superPDF/rotated.pdf",
  "pages": 4,
  "bytes": 1813
}

Add page labels

POST/v1/tools/pdf_add_page_labels

Add page numbers or a footer. Use {page} and {total} in the text.

Request body

Field	Type	Description
`input` required	string	Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
`pages`	string	Page numbers or ranges, such as "1, 3-5". Omit for every page. At most 200 characters.
`text`	string	1 to 120 characters. Default `"{page} / {total}"`.
`output` required	string	Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`output`	string
`pages`	integer
`bytes`	integer

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

curl -s http://127.0.0.1:7341/v1/tools/pdf_add_page_labels \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "report.pdf",
    "text": "Page {page} of {total}",
    "output": "numbered.pdf"
  }'

import { callTool, type NewFile } from './superpdf.ts';

const result = await callTool<NewFile>('pdf_add_page_labels', {
  input: 'report.pdf',
  text: 'Page {page} of {total}',
  output: 'numbered.pdf',
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_add_page_labels", {
    "input": "report.pdf",
    "text": "Page {page} of {total}",
    "output": "numbered.pdf",
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{
  "input": "report.pdf",
  "text": "Page {page} of {total}",
  "output": "numbered.pdf"
}`
	result, err := CallTool[NewFile]("pdf_add_page_labels", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "output": "/Users/<you>/Documents/superPDF/numbered.pdf",
  "pages": 4,
  "bytes": 2773
}

Add a watermark

POST/v1/tools/pdf_add_watermark

Stamp text diagonally across pages, such as DRAFT or CONFIDENTIAL.

Request body

Field	Type	Description
`input` required	string	Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
`pages`	string	Page numbers or ranges, such as "1, 3-5". Omit for every page. At most 200 characters.
`text` required	string	1 to 60 characters.
`output` required	string	Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`output`	string
`pages`	integer
`bytes`	integer

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

curl -s http://127.0.0.1:7341/v1/tools/pdf_add_watermark \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "report.pdf",
    "text": "DRAFT",
    "output": "draft.pdf"
  }'

import { callTool, type NewFile } from './superpdf.ts';

const result = await callTool<NewFile>('pdf_add_watermark', {
  input: 'report.pdf',
  text: 'DRAFT',
  output: 'draft.pdf',
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_add_watermark", {
    "input": "report.pdf",
    "text": "DRAFT",
    "output": "draft.pdf",
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{
  "input": "report.pdf",
  "text": "DRAFT",
  "output": "draft.pdf"
}`
	result, err := CallTool[NewFile]("pdf_add_watermark", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "output": "/Users/<you>/Documents/superPDF/draft.pdf",
  "pages": 4,
  "bytes": 2917
}

Split a PDF

POST/v1/tools/pdf_split

Split one PDF into several new files: one per comma-separated range (mode "ranges"), or one per page (mode "pages"). Files are written to output_folder.

Request body

Field	Type	Description
`input` required	string	Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
`pages`	string	Page numbers or ranges, such as "1, 3-5". Omit for every page. At most 200 characters.
`mode`	string	One of `ranges`, `pages`. Default `"ranges"`.
`output_folder` required	string	Folder for the new files, inside an allowed folder; created if missing.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`outputs`	array of objects
`outputs[].output`	string
`outputs[].pages`	integer
`outputs[].bytes`	integer

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

curl -s http://127.0.0.1:7341/v1/tools/pdf_split \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "report.pdf",
    "mode": "pages",
    "output_folder": "pages"
  }'

import { callTool } from './superpdf.ts';

const result = await callTool<Record<string, unknown>>('pdf_split', {
  input: 'report.pdf',
  mode: 'pages',
  output_folder: 'pages',
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_split", {
    "input": "report.pdf",
    "mode": "pages",
    "output_folder": "pages",
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{
  "input": "report.pdf",
  "mode": "pages",
  "output_folder": "pages"
}`
	result, err := CallTool[any]("pdf_split", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "outputs": [
    {
      "output": "/Users/<you>/Documents/superPDF/pages/report-page-1.pdf",
      "pages": 1,
      "bytes": 1003
    },
    {
      "output": "/Users/<you>/Documents/superPDF/pages/report-page-2.pdf",
      "pages": 1,
      "bytes": 954
    },
    {
      "output": "/Users/<you>/Documents/superPDF/pages/report-page-3.pdf",
      "pages": 1,
      "bytes": 948
    },
    {
      "output": "/Users/<you>/Documents/superPDF/pages/report-page-4.pdf",
      "pages": 1,
      "bytes": 937
    }
  ]
}

Convert an Office file to PDF

POST/v1/tools/pdf_from_office

Convert a Word, Excel, PowerPoint or OpenDocument file (.docx, .xlsx, .pptx, .odt, .ods, .odp) to a new PDF with LibreOffice installed on this computer. Fails with an install hint when LibreOffice isn't installed.

Request body

Field	Type	Description
`input` required	string	Path to the Office file inside an allowed folder (absolute, or relative to the first allowed folder).
`output` required	string	Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`output`	string
`pages`	integer
`bytes`	integer
`engine`	`"LibreOffice"`

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

curl -s http://127.0.0.1:7341/v1/tools/pdf_from_office \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "input": "budget.xlsx", "output": "budget.pdf" }'

import { callTool } from './superpdf.ts';

const result = await callTool<Record<string, unknown>>('pdf_from_office', {
  input: 'budget.xlsx',
  output: 'budget.pdf',
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_from_office", {
    "input": "budget.xlsx",
    "output": "budget.pdf",
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{ "input": "budget.xlsx", "output": "budget.pdf" }`
	result, err := CallTool[any]("pdf_from_office", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "output": "/Users/<you>/Documents/superPDF/budget.pdf",
  "pages": 2,
  "bytes": 28304,
  "engine": "LibreOffice"
}

Remove document properties

POST/v1/tools/pdf_remove_metadata

Write a copy without author, title, subject, keywords, creator and producer properties.

Request body

Field	Type	Description
`input` required	string	Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
`output` required	string	Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`output`	string
`pages`	integer
`bytes`	integer

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

curl -s http://127.0.0.1:7341/v1/tools/pdf_remove_metadata \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "input": "report.pdf", "output": "clean.pdf" }'

import { callTool, type NewFile } from './superpdf.ts';

const result = await callTool<NewFile>('pdf_remove_metadata', {
  input: 'report.pdf',
  output: 'clean.pdf',
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_remove_metadata", {
    "input": "report.pdf",
    "output": "clean.pdf",
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{ "input": "report.pdf", "output": "clean.pdf" }`
	result, err := CallTool[NewFile]("pdf_remove_metadata", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "output": "/Users/<you>/Documents/superPDF/clean.pdf",
  "pages": 4,
  "bytes": 1759
}

Repair a PDF

POST/v1/tools/pdf_repair

Rewrite a damaged PDF and rebuild its cross-reference table. Reports what was fixed.

Request body

Field	Type	Description
`input` required	string	Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
`output` required	string	Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`output`	string
`pages`	integer
`bytes`	integer
`fixed`	array of strings

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

curl -s http://127.0.0.1:7341/v1/tools/pdf_repair \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "input": "report.pdf", "output": "repaired.pdf" }'

import { callTool } from './superpdf.ts';

const result = await callTool<Record<string, unknown>>('pdf_repair', {
  input: 'report.pdf',
  output: 'repaired.pdf',
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_repair", {
    "input": "report.pdf",
    "output": "repaired.pdf",
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{ "input": "report.pdf", "output": "repaired.pdf" }`
	result, err := CallTool[any]("pdf_repair", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "output": "/Users/<you>/Documents/superPDF/repaired.pdf",
  "pages": 4,
  "bytes": 1872,
  "fixed": []
}

Password-protect a PDF

POST/v1/tools/pdf_protect

Encrypt a copy with AES-256 so it needs a password to open. Only use a password the user gave you for this purpose.

Request body

Field	Type	Description
`input` required	string	Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
`password` required	string	1 to 127 characters.
`output` required	string	Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`output`	string
`pages`	integer
`bytes`	integer

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

curl -s http://127.0.0.1:7341/v1/tools/pdf_protect \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "report.pdf",
    "password": "correct horse battery",
    "output": "protected.pdf"
  }'

import { callTool, type NewFile } from './superpdf.ts';

const result = await callTool<NewFile>('pdf_protect', {
  input: 'report.pdf',
  password: 'correct horse battery',
  output: 'protected.pdf',
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_protect", {
    "input": "report.pdf",
    "password": "correct horse battery",
    "output": "protected.pdf",
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{
  "input": "report.pdf",
  "password": "correct horse battery",
  "output": "protected.pdf"
}`
	result, err := CallTool[NewFile]("pdf_protect", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "output": "/Users/<you>/Documents/superPDF/protected.pdf",
  "pages": 4,
  "bytes": 2648
}

Remove a PDF password

POST/v1/tools/pdf_unlock

Write a decrypted copy using a password the user knows. Never guesses passwords.

Request body

Field	Type	Description
`input` required	string	Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
`password`	string	At most 127 characters. Default `""`.
`output` required	string	Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`output`	string
`pages`	integer
`bytes`	integer

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

curl -s http://127.0.0.1:7341/v1/tools/pdf_unlock \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "protected.pdf",
    "password": "correct horse battery",
    "output": "unlocked.pdf"
  }'

import { callTool, type NewFile } from './superpdf.ts';

const result = await callTool<NewFile>('pdf_unlock', {
  input: 'protected.pdf',
  password: 'correct horse battery',
  output: 'unlocked.pdf',
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_unlock", {
    "input": "protected.pdf",
    "password": "correct horse battery",
    "output": "unlocked.pdf",
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{
  "input": "protected.pdf",
  "password": "correct horse battery",
  "output": "unlocked.pdf"
}`
	result, err := CallTool[NewFile]("pdf_unlock", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "output": "/Users/<you>/Documents/superPDF/unlocked.pdf",
  "pages": 4,
  "bytes": 1976
}

Run a pipeline

POST/v1/tools/pdf_run_pipeline

Apply 1–10 steps in order and write one new PDF. Step actions: extract, remove, rotate, crop, scale, flatten, labels, watermark, metadata-clear; options as in the matching tools (e.g. {"action":"rotate","options":{"pages":"1","angle":90}}).

Request body

Field	Type	Description
`input` required	string	Path to a PDF inside an allowed folder (absolute, or relative to the first allowed folder).
`steps` required	array of objects	Steps run in order, such as [{"action":"rotate","options":{"pages":"1","angle":90}}]. 1 to 10 items.
`output` required	string	Path for the new PDF, inside an allowed folder. Must not exist yet; superPDF never overwrites files.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`output`	string
`pages`	integer
`bytes`	integer

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

curl -s http://127.0.0.1:7341/v1/tools/pdf_run_pipeline \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "report.pdf",
    "steps": [
      {"action": "extract", "options": {"pages": "1-2"}},
      {"action": "labels", "options": {"text": "{page} / {total}"}}
    ],
    "output": "brief.pdf"
  }'

import { callTool, type NewFile } from './superpdf.ts';

const result = await callTool<NewFile>('pdf_run_pipeline', {
  input: 'report.pdf',
  steps: [
    { action: 'extract', options: { pages: '1-2' } },
    { action: 'labels', options: { text: '{page} / {total}' } },
  ],
  output: 'brief.pdf',
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_run_pipeline", {
    "input": "report.pdf",
    "steps": [
        {"action": "extract", "options": {"pages": "1-2"}},
        {"action": "labels", "options": {"text": "{page} / {total}"}},
    ],
    "output": "brief.pdf",
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{
  "input": "report.pdf",
  "steps": [
    {"action": "extract", "options": {"pages": "1-2"}},
    {"action": "labels", "options": {"text": "{page} / {total}"}}
  ],
  "output": "brief.pdf"
}`
	result, err := CallTool[NewFile]("pdf_run_pipeline", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "output": "/Users/<you>/Documents/superPDF/brief.pdf",
  "pages": 2,
  "bytes": 1843
}

Run a batch

POST/v1/tools/pdf_run_batch

Apply the same 1–10 pipeline steps to each of 1–50 PDFs, one file at a time. Each result is written to output_folder as <name>-<suffix>.pdf. A file that fails is skipped and listed in failed with the reason; the rest continue.

Request body

Field	Type	Description
`inputs` required	array of strings	PDF paths to process. 1 to 50 items.
`steps` required	array of objects	Steps run in order, such as [{"action":"rotate","options":{"pages":"1","angle":90}}]. 1 to 10 items.
`output_folder` required	string	Folder for the new files, inside an allowed folder; created if missing.
`suffix`	string	Added to each output file name. Matches `^[A-Za-z0-9_-]{1,40}$`. Default `"processed"`.

Response

200 The result. Any new files are written inside the allowed folders.

Field	Type
`outputs`	array of objects
`outputs[].output`	string
`outputs[].pages`	integer
`outputs[].bytes`	integer
`outputs[].input`	string
`failed`	array of objects
`failed[].input`	string
`failed[].error`	string

Errors: 400, 401, 403, 409, 413, 415, 422, 429, 500. See Errors.

Example

curl -s http://127.0.0.1:7341/v1/tools/pdf_run_batch \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": ["report.pdf", "appendix.pdf"],
    "steps": [{"action": "watermark", "options": {"text": "DRAFT"}}],
    "output_folder": "drafts"
  }'

import { callTool, type BatchResult } from './superpdf.ts';

const result = await callTool<BatchResult>('pdf_run_batch', {
  inputs: ['report.pdf', 'appendix.pdf'],
  steps: [{ action: 'watermark', options: { text: 'DRAFT' } }],
  output_folder: 'drafts',
});
console.log(JSON.stringify(result, null, 2));

import json

from superpdf import call_tool

result = call_tool("pdf_run_batch", {
    "inputs": ["report.pdf", "appendix.pdf"],
    "steps": [{"action": "watermark", "options": {"text": "DRAFT"}}],
    "output_folder": "drafts",
})
print(json.dumps(result, indent=2))

package main

import (
	"encoding/json"
	"fmt"
	"log"
)

func main() {
	input := `{
  "inputs": ["report.pdf", "appendix.pdf"],
  "steps": [{"action": "watermark", "options": {"text": "DRAFT"}}],
  "output_folder": "drafts"
}`
	result, err := CallTool[BatchResult]("pdf_run_batch", json.RawMessage(input))
	if err != nil {
		log.Fatal(err)
	}
	out, _ := json.MarshalIndent(result, "", "  ")
	fmt.Println(string(out))
}

Response

{
  "outputs": [
    {
      "input": "/Users/<you>/Documents/superPDF/report.pdf",
      "output": "/Users/<you>/Documents/superPDF/drafts/report-processed.pdf",
      "pages": 4,
      "bytes": 2917
    },
    {
      "input": "/Users/<you>/Documents/superPDF/appendix.pdf",
      "output": "/Users/<you>/Documents/superPDF/drafts/appendix-processed.pdf",
      "pages": 1,
      "bytes": 1405
    }
  ],
  "failed": []
}

Run a tool in the background

POST/v1/jobs

Queues a tool call and returns at once with the job. Jobs run one at a time. Poll GET /v1/jobs/{id}, or pass callback_url to receive a signed event when it finishes. Failed callback deliveries are retried up to 5 times with exponential backoff (1, 2, 4 and 8 seconds).

Request body

Field	Type	Description
`tool` required	string	The tool to run: any name from `GET /v1/tools`.
`input` required	object	The tool’s input: the same fields as its own endpoint below.
`callback_url`	string	Where to POST a signed event when the job finishes. Loopback addresses (127.0.0.1, localhost, [::1]) are allowed by default; other origins only when the API was started with --webhook-allow <origin>. At most 2,048 characters.

Response

202 Queued.

Field	Type	Description
`id`	string	None
`tool`	string	None
`status`	string	One of `queued`, `running`, `succeeded`, `failed`.
`progress`	object or null	Latest progress from tools that report it (merge, split, pipelines, batches).
`progress.progress`	number	None
`progress.total`	number	None
`progress.message`	string	None
`created_at`	string	ISO 8601 time.
`started_at`	string or null	None
`finished_at`	string or null	None
`result`	any	Once succeeded: the same result POST /v1/tools/{tool} returns.
`error`	problem details object	RFC 9457 Problem Details.
`callback`	object	None
`callback.url`	string	None
`callback.status`	string	One of `pending`, `delivering`, `delivered`, `failed`.
`callback.attempts`	integer	None
`callback.last_status`	integer or null	HTTP status of the last attempt; null when the receiver could not be reached.

Errors: 400, 401, 403, 413, 415, 422, 429. See Errors.

Example

curl http://127.0.0.1:7341/v1/jobs \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "pdf_run_batch",
    "input": {
      "inputs": ["report.pdf", "appendix.pdf"],
      "steps": [{ "action": "watermark", "options": { "text": "DRAFT" } }],
      "output_folder": "drafts"
    },
    "callback_url": "http://127.0.0.1:8080/hooks/superpdf"
  }'

import { request, type BatchResult, type Job } from './superpdf.ts';

const job = await request<Job<BatchResult>>('POST', '/v1/jobs', {
  tool: 'pdf_run_batch',
  input: {
    inputs: ['report.pdf', 'appendix.pdf'],
    steps: [{ action: 'watermark', options: { text: 'DRAFT' } }],
    output_folder: 'drafts',
  },
  callback_url: 'http://127.0.0.1:8080/hooks/superpdf',
});
console.log(`${job.id} is ${job.status}`);

from superpdf import Job, request

job: Job = request("POST", "/v1/jobs", {
    "tool": "pdf_run_batch",
    "input": {
        "inputs": ["report.pdf", "appendix.pdf"],
        "steps": [{"action": "watermark", "options": {"text": "DRAFT"}}],
        "output_folder": "drafts",
    },
    "callback_url": "http://127.0.0.1:8080/hooks/superpdf",
})
print(f"{job['id']} is {job['status']}")

package main

import (
	"fmt"
	"log"
)

func main() {
	var job Job[BatchResult]
	err := Request("POST", "/v1/jobs", map[string]any{
		"tool": "pdf_run_batch",
		"input": map[string]any{
			"inputs": []string{"report.pdf", "appendix.pdf"},
			"steps": []map[string]any{
				{"action": "watermark", "options": map[string]string{"text": "DRAFT"}},
			},
			"output_folder": "drafts",
		},
		"callback_url": "http://127.0.0.1:8080/hooks/superpdf",
	}, &job)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s is %s\n", job.ID, job.Status)
}

Response

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /v1/jobs/job_f5a4c3fc-c43f-4655-8a35-f8821bf7cd4f

{
  "id": "job_f5a4c3fc-c43f-4655-8a35-f8821bf7cd4f",
  "tool": "pdf_run_batch",
  "status": "running",
  "progress": null,
  "created_at": "2026-10-11T01:39:03.888Z",
  "started_at": "2026-10-11T01:39:03.889Z",
  "finished_at": null,
  "callback": {
    "url": "http://127.0.0.1:8080/hooks/superpdf",
    "status": "pending",
    "attempts": 0,
    "last_status": null
  }
}

List jobs

GET/v1/jobs

Response

200 Jobs from this server process, newest first. Finished jobs are kept for an hour.

Field	Type	Description
`jobs`	array of objects	None
`jobs[].id`	string	None
`jobs[].tool`	string	None
`jobs[].status`	string	One of `queued`, `running`, `succeeded`, `failed`.
`jobs[].progress`	object or null	Latest progress from tools that report it (merge, split, pipelines, batches).
`jobs[].progress.progress`	number	None
`jobs[].progress.total`	number	None
`jobs[].progress.message`	string	None
`jobs[].created_at`	string	ISO 8601 time.
`jobs[].started_at`	string or null	None
`jobs[].finished_at`	string or null	None
`jobs[].result`	any	Once succeeded: the same result POST /v1/tools/{tool} returns.
`jobs[].error`	problem details object	RFC 9457 Problem Details.
`jobs[].callback`	object	None
`jobs[].callback.url`	string	None
`jobs[].callback.status`	string	One of `pending`, `delivering`, `delivered`, `failed`.
`jobs[].callback.attempts`	integer	None
`jobs[].callback.last_status`	integer or null	HTTP status of the last attempt; null when the receiver could not be reached.

Errors: 401, 403. See Errors.

Example

Terminal

curl -s http://127.0.0.1:7341/v1/jobs \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN"

Response

{
  "jobs": [
    {
      "id": "job_c5ece8a8-5f0f-4121-97ec-9ca994a94c10",
      "tool": "pdf_run_batch",
      "status": "succeeded",
      "progress": {
        "progress": 2,
        "total": 2,
        "message": "2 of 2 files"
      },
      "created_at": "2026-10-11T01:55:36.410Z",
      "started_at": "2026-10-11T01:55:36.410Z",
      "finished_at": "2026-10-11T01:55:36.414Z",
      "result": {
        "outputs": [
          {
            "input": "/Users/<you>/Documents/superPDF/report.pdf",
            "output": "/Users/<you>/Documents/superPDF/drafts/report-processed.pdf",
            "pages": 4,
            "bytes": 2916
          },
          {
            "input": "/Users/<you>/Documents/superPDF/appendix.pdf",
            "output": "/Users/<you>/Documents/superPDF/drafts/appendix-processed.pdf",
            "pages": 1,
            "bytes": 1405
          }
        ],
        "failed": []
      }
    }
  ]
}

Get a job

GET/v1/jobs/{id}

Path parameters

Parameter	Type	Description
`id`	string	The job id from POST /v1/jobs.

Response

200 The job, with its result once it has succeeded.

Field	Type	Description
`id`	string	None
`tool`	string	None
`status`	string	One of `queued`, `running`, `succeeded`, `failed`.
`progress`	object or null	Latest progress from tools that report it (merge, split, pipelines, batches).
`progress.progress`	number	None
`progress.total`	number	None
`progress.message`	string	None
`created_at`	string	ISO 8601 time.
`started_at`	string or null	None
`finished_at`	string or null	None
`result`	any	Once succeeded: the same result POST /v1/tools/{tool} returns.
`error`	problem details object	RFC 9457 Problem Details.
`callback`	object	None
`callback.url`	string	None
`callback.status`	string	One of `pending`, `delivering`, `delivered`, `failed`.
`callback.attempts`	integer	None
`callback.last_status`	integer or null	HTTP status of the last attempt; null when the receiver could not be reached.

Errors: 401, 403, 404. See Errors.

Example

Terminal

curl -s http://127.0.0.1:7341/v1/jobs/$JOB \
  -H "Authorization: Bearer $SUPERPDF_API_TOKEN"

Response

{
  "id": "job_c5ece8a8-5f0f-4121-97ec-9ca994a94c10",
  "tool": "pdf_run_batch",
  "status": "succeeded",
  "progress": {
    "progress": 2,
    "total": 2,
    "message": "2 of 2 files"
  },
  "created_at": "2026-10-11T01:55:36.410Z",
  "started_at": "2026-10-11T01:55:36.410Z",
  "finished_at": "2026-10-11T01:55:36.414Z",
  "result": {
    "outputs": [
      {
        "input": "/Users/<you>/Documents/superPDF/report.pdf",
        "output": "/Users/<you>/Documents/superPDF/drafts/report-processed.pdf",
        "pages": 4,
        "bytes": 2916
      },
      {
        "input": "/Users/<you>/Documents/superPDF/appendix.pdf",
        "output": "/Users/<you>/Documents/superPDF/drafts/appendix-processed.pdf",
        "pages": 1,
        "bytes": 1405
      }
    ],
    "failed": []
  }
}

This document

GET/openapi.json

Response

200 The OpenAPI 3.1 document. No token needed.

A JSON object; the example below shows its fields.

Example

Terminal

curl -s http://127.0.0.1:7341/openapi.json | jq .info

Output

{
  "title": "superPDF local API",
  "version": "0.1.0",
  "description": "The superPDF tools over HTTP, served by `superpdf serve --allow-di…"
}