Paperless-ngx

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.

Security Scan

The skill's instructions match its described purpose (interacting with Paperless-ngx via its REST API) but the registry metadata omits required environment variables and credential declarations, which is an important inconsistency you should address before installing.

Purpose & Capability

SKILL.md describes exactly the Paperless-ngx REST operations you'd expect (search, upload, download, metadata updates, delete, tags, correspondents, bulk operations). However, the skill's registry metadata lists no required environment variables or primary credential while SKILL.md explicitly requires PAPERLESS_URL and PAPERLESS_TOKEN — a metadata mismatch that prevents clear permission/credential auditing.

Instruction Scope

Runtime instructions are narrowly scoped to making HTTP requests to the user-supplied Paperless-ngx instance and to reading two environment variables (PAPERLESS_URL and PAPERLESS_TOKEN). There are no instructions to read unrelated files, other env vars, or to send data to external endpoints beyond the specified base URL.

Install Mechanism

No install spec and no code files (instruction-only). This is low-risk from an install perspective because nothing is written to disk or downloaded by the skill itself.

Credentials

Requesting an API token and base URL is appropriate for this functionality, but the skill does not declare these required env vars in the registry metadata. Also note the PAPERLESS_TOKEN, if provided, can permit sensitive actions (upload, delete, bulk edit). The token's broad privileges are proportional to the operations shown but warrant caution and least-privilege use.

Persistence & Privilege

The skill does not request permanent presence (always: false), has no install actions, and does not modify other skills or system-wide configuration. Normal autonomous invocation is allowed (platform default).

What to consider before installing

This skill appears to do what it says (talk to a Paperless-ngx REST API), but there are two things to resolve before trusting it: (1) the SKILL.md requires PAPERLESS_URL and PAPERLESS_TOKEN but the registry metadata doesn't declare them — ask the publisher to correct the metadata so you can audit required secrets; (2) the API token grants powerful actions (upload, delete, bulk edits). Only provide a token with the minimum permissions needed, store it securely, and be prepared to revoke/rotate it if something unexpected happens. Because the source/homepage is unknown, prefer installing only if you can verify the publisher or obtain the skill's source/instructions from a trusted location. If possible, test with a read-only or limited account first rather than an admin token.

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

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

curl -s "$PAPERLESS_URL/api/documents/{id}/" \
  -H "Authorization: Token $PAPERLESS_TOKEN"

Download Document

# 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

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

curl -s -X PATCH "$PAPERLESS_URL/api/documents/{id}/" \
  -H "Authorization: Token $PAPERLESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Title", "correspondent": 1, "tags": [1, 2]}'

Delete Document

curl -s -X DELETE "$PAPERLESS_URL/api/documents/{id}/" \
  -H "Authorization: Token $PAPERLESS_TOKEN"

Organization Endpoints

Tags

# List tags
curl -s "$PAPERLESS_URL/api/tags/" -H "Authorization: Token $PAPERLESS_TOKEN"

# Create tag
curl -s -X POST "$PAPERLESS_URL/api/tags/" \
  -H "Authorization: Token $PAPERLESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Important", "color": "#ff0000"}'

Correspondents

# List correspondents
curl -s "$PAPERLESS_URL/api/correspondents/" -H "Authorization: Token $PAPERLESS_TOKEN"

# Create correspondent
curl -s -X POST "$PAPERLESS_URL/api/correspondents/" \
  -H "Authorization: Token $PAPERLESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "ACME Corp"}'

Document Types

# List document types
curl -s "$PAPERLESS_URL/api/document_types/" -H "Authorization: Token $PAPERLESS_TOKEN"

# Create document type
curl -s -X POST "$PAPERLESS_URL/api/document_types/" \
  -H "Authorization: Token $PAPERLESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Invoice"}'

Bulk Operations

curl -s -X POST "$PAPERLESS_URL/api/documents/bulk_edit/" \
  -H "Authorization: Token $PAPERLESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [1, 2, 3],
    "method": "add_tag",
    "parameters": {"tag": 5}
  }'

Methods: set_correspondent, set_document_type, add_tag, remove_tag, delete, reprocess.

Task Status

After upload, check task status:

curl -s "$PAPERLESS_URL/api/tasks/?task_id={uuid}" \
  -H "Authorization: Token $PAPERLESS_TOKEN"

Response Handling

• List endpoints return {"count": N, "results": [...]} with pagination
• Single objects return the object directly
• Use ?page=2 for pagination
• Add ?ordering=-created for sorting (prefix - for descending)