Menu
Search documents in Paperless-ngx via REST API. Full-text search, tag/correspondent filtering, and direct links to documents.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Pressure-test an assumption, architecture decision, estimate, or inherited constraint. Use when the user asks to challenge a belief, play devil's advocate, test reasoning, or find a simpler alternative.
Explain a code location, component, command, or user-facing system flow. Use when the user asks what code does, why it exists, how a feature works, or wants a trace of entry points, branches, dependencies, and side effects.
Prepare difficult technical or delivery news for a client, stakeholder, or team. Use for delays, incidents, security findings, cost changes, failed approaches, or other conversations where clarity and trust matter.
Plan and work through project, client, vendor, or team offboarding. Use for handovers, access removal, ownership transfer, documentation, credential rotation, data cleanup, and knowledge-transfer checklists.
Discover how a codebase already handles a concern before extending it. Use when asked how the repository does something, where a pattern lives, whether implementations are consistent, or what convention new work should follow.
Help the user think through a confusing problem or decision by asking focused questions and reflecting their reasoning. Use when they want to think out loud, untangle a problem, or find the question beneath the question.
| name | paperless-search |
| description | Search documents in Paperless-ngx via REST API. Full-text search, tag/correspondent filtering, and direct links to documents. |
| license | MIT |
| metadata | {"author":"Nicolai Schmid","version":"2.0.0","requires":["curl","jq"]} |
Search your Paperless-ngx document archive via the REST API.
Config file: ~/.config/paperless-search/config.json
{
"url": "https://paperless.example.com",
"token": "your-api-token-here"
}
If requests fail, verify the config:
# Check config exists and is valid JSON
cat ~/.config/paperless-search/config.json | jq .
# Test connection
curl -s -H "Authorization: Token $(jq -r .token ~/.config/paperless-search/config.json)" \
"$(jq -r .url ~/.config/paperless-search/config.json)/api/documents/?page_size=1" | jq '.count'
Common issues:
401 Unauthorized: Token is invalid/expired → regenerate in web UIConnection refused: URL is wrong or server is downnull or parse error: Config file is missing or malformedIf config is broken, guide the user to provide:
https://paperless.example.com)Then create/update the config:
mkdir -p ~/.config/paperless-search
cat > ~/.config/paperless-search/config.json << 'EOF'
{
"url": "USER_PROVIDED_URL",
"token": "USER_PROVIDED_TOKEN"
}
EOF
# Load config into variables
PAPERLESS_URL=$(jq -r .url ~/.config/paperless-search/config.json)
PAPERLESS_TOKEN=$(jq -r .token ~/.config/paperless-search/config.json)
# Full-text search
curl -s -H "Authorization: Token $PAPERLESS_TOKEN" \
"$PAPERLESS_URL/api/documents/?query=invoice+january+2025" | jq '.results[] | {id, title, created}'
# Get document with full OCR content
curl -s -H "Authorization: Token $PAPERLESS_TOKEN" \
"$PAPERLESS_URL/api/documents/123/" | jq -r '.content'
# List correspondents
curl -s -H "Authorization: Token $PAPERLESS_TOKEN" \
"$PAPERLESS_URL/api/correspondents/" | jq '.results[] | {id, name}'
# Filter by correspondent
curl -s -H "Authorization: Token $PAPERLESS_TOKEN" \
"$PAPERLESS_URL/api/documents/?correspondent__id=5" | jq
# Filter by date range
curl -s -H "Authorization: Token $PAPERLESS_TOKEN" \
"$PAPERLESS_URL/api/documents/?created__date__gte=2024-01-01&created__date__lte=2024-12-31" | jq
# List tags
curl -s -H "Authorization: Token $PAPERLESS_TOKEN" \
"$PAPERLESS_URL/api/tags/" | jq '.results[] | {id, name}'
# List document types
curl -s -H "Authorization: Token $PAPERLESS_TOKEN" \
"$PAPERLESS_URL/api/document_types/" | jq '.results[] | {id, name}'
| Endpoint | Description |
|---|---|
/api/documents/ | List/search documents |
/api/documents/{id}/ | Get single document with full content |
/api/tags/ | List all tags |
/api/correspondents/ | List all correspondents |
/api/document_types/ | List all document types |
/api/documents/| Parameter | Example | Description |
|---|---|---|
query | query=contract+2022 | Full-text search |
correspondent__id | correspondent__id=5 | Filter by correspondent |
tags__id__all | tags__id__all=1,2 | Must have all tags |
document_type__id | document_type__id=3 | Filter by type |
created__date__gte | created__date__gte=2024-01-01 | Created after |
created__date__lte | created__date__lte=2024-12-31 | Created before |
ordering | ordering=-created | Sort order |
page_size | page_size=50 | Results per page |
When linking to documents, always use the base URL from the config file:
PAPERLESS_URL=$(jq -r .url ~/.config/paperless-search/config.json)
echo "$PAPERLESS_URL/documents/{id}/details"
Do NOT hardcode or guess the URL - always read it from the config.