메뉴
Search documents in Paperless-ngx via REST API. Full-text search, tag/correspondent filtering, and direct links to documents.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
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.