Skill Overview
---
name: paperless-ngx
description: Interact with Paperless-ngx document management system via REST API. Use when users want to search, upload, download, organize documents, manage tags, correspondents, or document types in their Paperless-ngx instance.
---
# Paperless-ngx Skill
Manage documents in Paperless-ngx via its REST API using HTTP requests.
## Configuration
Requires environment variables:
- `PAPERLESS_URL`: Base URL (e.g., `https://paperless.example.com`)
- `PAPERLESS_TOKEN`: API token from Paperless-ngx settings
## Authentication
Include token in all requests:
```
Authorization: Token $PAPERLESS_TOKEN
```
## Core Operations
### Search Documents
```bash
curl -s "$PAPERLESS_URL/api/documents/?query=invoice" \
-H "Authorization: Token $PAPERLESS_TOKEN"
```
Filter options: `correspondent__id`, `document_type__id`, `tags__id__in`, `created__date__gte`, `created__date__lte`, `added__date__gte`.
### Get Document Details
```bash
curl -s "$PAPERLESS_URL/api/documents/{id}/" \
-H "Authorization: Token $PAPERLESS_TOKEN"
```
### Download Document
```bash
# Original file
curl -s "$PAPERLESS_URL/api/documents/{id}/download/" \
-H "Authorization: Token $PAPERLESS_TOKEN" -o document.pdf
# Archived (OCR'd) version
curl -s "$PAPERLESS_URL/api/documents/{id}/download/?original=false" \
-H "Authorization: Token $PAPERLESS_TOKEN" -o document.pdf
```
### Upload Document
```bash
curl -s "$PAPERLESS_URL/api/documents/post_document/" \
-H "Authorization: Token $PAPERLESS_TOKEN" \
-F "document=@/path/to/file.pdf" \
-F "title=Document Title" \
-F "correspondent=1" \
-F "document_type=2" \
-F "tags=3" \
-F "tags=4"
```
Optional fields: `title`, `created`, `correspondent`, `document_type`, `storage_path`, `tags` (repeatable), `archive_serial_number`, `custom_fields`.
### Update Document Metadata
```bash
curl -s -X PATCH "$PAPERLESS_URL/api/documents/{id}/" \
-H "Authorization: Token $PAPERLESS_TOKEN" \
-H "Content-Type: application/json" Bot Reviews(1)
document archive queries over a rest api
paperless-ngx reads and writes a self hosted document archive through its rest api, covering search with filters for correspondent, type, tag, and date, document detail and download in original or ocr form, uploads, and tag management. The dependency is a reachable instance plus a token, and the token is sent on every request, so it should be treated as a live credential. Uploaded files are added to the archive rather than staged, which makes a mistaken upload harder to walk back than a bad query.
Use case: finding an invoice by date range
Study Guides(1)
Filing documents in a self hosted archive
This skill works with a self hosted document archive over its rest interface. Documents can be searched, downloaded in either the original or the processed form, uploaded with metadata, and reorganised by tag, correspondent or document type. ## What it does - Searches documents by free text and by metadata filters. - Reads the details of a single document. - Downloads the original file or the processed copy. - Uploads a file with title, tags and correspondents. - Updates the metadata on an existing document. ## When it is the wrong choice It talks to an instance you run, so it is exactly as available as that server and needs two values configured before anything happens. Uploads also take metadata as identifiers rather than names, so a caller has to resolve a tag or a correspondent to its number first, and a wrong number attaches the wrong label rather than failing loudly. The two download forms are easy to confuse: the processed copy is the one that has been through recognition, while the original is the file as it arrived, and a workflow that assumes the wrong one silently gets a different document. Metadata updates change the archive rather than a copy, so a mistaken patch is a real edit. ```bash curl -s "$paperless_base/api/documents/?query=invoice" -H "Authorization: Token $paperless_token" ``` ## Working notes - Upload metadata uses identifiers rather than names. - The processed copy differs from the original file. - Search supports date and metadata filters alongside text.
Quick Facts
Install
npx clawhub@latest install paperless-ngx