Back to Details

paperless-search

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Paperless Document Search

Paperless-ngx 文档搜索

Search your Paperless-ngx document archive via the REST API.
通过REST API搜索你的Paperless-ngx文档归档。

Configuration

配置

Config file: 
~/.config/paperless-search/config.json
json
{
  "url": "https://paperless.example.com",
  "token": "your-api-token-here"
}
配置文件：
~/.config/paperless-search/config.json
json
{
  "url": "https://paperless.example.com",
  "token": "your-api-token-here"
}

Getting an API token

获取API令牌

  1. Log into your Paperless web UI
  2. Click your username (top right) → "My Profile"
  3. Click the circular arrow button to generate/regenerate a token
  1. 登录Paperless网页UI
  2. 点击右上角的用户名 → "我的个人资料"
  3. 点击圆形箭头按钮生成/重新生成令牌

Troubleshooting config

配置故障排查

If requests fail, verify the config:
bash
undefined
如果请求失败，请验证配置：
bash
undefined

Check config exists and is valid JSON

Check config exists and is valid JSON

cat ~/.config/paperless-search/config.json | jq .
cat ~/.config/paperless-search/config.json | jq .

Test connection

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 UI
- `Connection refused`: URL is wrong or server is down
- `null` or parse error: Config file is missing or malformed

If config is broken, guide the user to provide:

1. Their Paperless-ngx URL (e.g., `https://paperless.example.com`)
2. A valid API token from their profile page

Then create/update the config:

```bash
mkdir -p ~/.config/paperless-search
cat > ~/.config/paperless-search/config.json << 'EOF'
{
  "url": "USER_PROVIDED_URL",
  "token": "USER_PROVIDED_TOKEN"
}
EOF
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'

**常见问题：**

- `401 Unauthorized`: 令牌无效/过期 → 在网页UI中重新生成
- `Connection refused`: URL错误或服务器已下线
- `null`或解析错误：配置文件缺失或格式错误

如果配置损坏，请引导用户提供：

1. 他们的Paperless-ngx URL（例如：`https://paperless.example.com`）
2. 来自个人资料页面的有效API令牌

然后创建/更新配置：

```bash
mkdir -p ~/.config/paperless-search
cat > ~/.config/paperless-search/config.json << 'EOF'
{
  "url": "USER_PROVIDED_URL",
  "token": "USER_PROVIDED_TOKEN"
}
EOF

API Examples

API 示例

bash
undefined
bash
undefined

Load config into variables

Load config into variables

PAPERLESS_URL=$(jq -r .url ~/.config/paperless-search/config.json) PAPERLESS_TOKEN=$(jq -r .token ~/.config/paperless-search/config.json)
PAPERLESS_URL=$(jq -r .url ~/.config/paperless-search/config.json) PAPERLESS_TOKEN=$(jq -r .token ~/.config/paperless-search/config.json)

Full-text search

Full-text search

curl -s -H "Authorization: Token $PAPERLESS_TOKEN"
"$PAPERLESS_URL/api/documents/?query=invoice+january+2025" | jq '.results[] | {id, title, created}'
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

Get document with full OCR content

curl -s -H "Authorization: Token $PAPERLESS_TOKEN"
"$PAPERLESS_URL/api/documents/123/" | jq -r '.content'
curl -s -H "Authorization: Token $PAPERLESS_TOKEN"
"$PAPERLESS_URL/api/documents/123/" | jq -r '.content'

List correspondents

List correspondents

curl -s -H "Authorization: Token $PAPERLESS_TOKEN"
"$PAPERLESS_URL/api/correspondents/" | jq '.results[] | {id, name}'
curl -s -H "Authorization: Token $PAPERLESS_TOKEN"
"$PAPERLESS_URL/api/correspondents/" | jq '.results[] | {id, name}'

Filter by correspondent

Filter by correspondent

curl -s -H "Authorization: Token $PAPERLESS_TOKEN"
"$PAPERLESS_URL/api/documents/?correspondent__id=5" | jq
curl -s -H "Authorization: Token $PAPERLESS_TOKEN"
"$PAPERLESS_URL/api/documents/?correspondent__id=5" | jq

Filter by date range

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
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

List tags

curl -s -H "Authorization: Token $PAPERLESS_TOKEN"
"$PAPERLESS_URL/api/tags/" | jq '.results[] | {id, name}'
curl -s -H "Authorization: Token $PAPERLESS_TOKEN"
"$PAPERLESS_URL/api/tags/" | jq '.results[] | {id, name}'

List document types

List document types

curl -s -H "Authorization: Token $PAPERLESS_TOKEN"
"$PAPERLESS_URL/api/document_types/" | jq '.results[] | {id, name}'
undefined
curl -s -H "Authorization: Token $PAPERLESS_TOKEN"
"$PAPERLESS_URL/api/document_types/" | jq '.results[] | {id, name}'
undefined

API Reference

API 参考

EndpointDescription
/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/
列出/搜索文档
/api/documents/{id}/
获取包含完整内容的单个文档
/api/tags/
列出所有标签
/api/correspondents/
列出所有联系人
/api/document_types/
列出所有文档类型

Query Parameters for 
/api/documents/

/api/documents/
的查询参数

ParameterExampleDescription
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
参数示例描述
query
query=contract+2022
全文搜索
correspondent__id
correspondent__id=5
按联系人筛选
tags__id__all
tags__id__all=1,2
必须包含所有指定标签
document_type__id
document_type__id=3
按类型筛选
created__date__gte
created__date__gte=2024-01-01
创建时间不早于
created__date__lte
created__date__lte=2024-12-31
创建时间不晚于
ordering
ordering=-created
排序顺序
page_size
page_size=50
每页结果数量

Document URL format

文档URL格式

When linking to documents, always use the base URL from the config file:
bash
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.
当链接到文档时，请始终使用配置文件中的基础URL：
bash
PAPERLESS_URL=$(jq -r .url ~/.config/paperless-search/config.json)
echo "$PAPERLESS_URL/documents/{id}/details"
请勿硬编码或猜测URL - 始终从配置文件中读取。