Documents

Documents are the core resource in Paperless-ngx. This page shows the essential CRUD examples. For the full feature set - downloading, searching, notes, next ASN, email, and upload - see the dedicated Documents page.

Models

See pypaperless/models/documents/document.py for all fields and pypaperless/models/types.py for enum and filter types, and the Paperless-ngx API docs for the upstream schema.

Fetch one

doc = await paperless.documents(42)
print(doc.title)
print(doc.created_date)  # datetime.date

Iterate

async for doc in paperless.documents:
    print(doc.id, doc.title)

# All documents in memory
all_docs = await paperless.documents.as_list()

Create (upload)

To upload a new document, use draft() + save(). The first positional argument to save() is the raw file content (bytes):

with open("invoice.pdf", "rb") as fh:
    raw = fh.read()

draft = paperless.documents.create()
draft.title = "Invoice 2024"
draft.correspondent = 7
draft.tags = [1, 3]

task_id = await paperless.documents.save(draft, raw)

save() returns a str task UUID. Monitor progress via paperless.tasks.

Update

doc = await paperless.documents(42)
doc.title = "Updated title"
doc.tags = [1, 2, 5]
changed = await paperless.documents.update(doc)

Delete

doc = await paperless.documents(42)
await paperless.documents.delete(doc)

Raises DeletionError on failure. Pass silent_fail=True to suppress it.

Document sub-service shortcuts

The Document model exposes three bound sub-services as properties. These are the same services as paperless.documents.notes, .history and .share_links, but with the document's primary key pre-filled:

doc = await paperless.documents(42)

# notes: cache-first by default, force_request=True to re-fetch from API
notes      = await doc.notes()                    # from cache (no HTTP request)
notes      = await doc.notes(force_request=True)  # fresh from API
note_draft = doc.notes.create(note="Checked.")
note_id    = await doc.notes.save(note_draft)
await doc.notes.delete(notes[0])

# history (read-only)
entries = await doc.history()              # list[DocumentHistory]

# share links (read-only from here, use paperless.share_links to create/delete)
links = await doc.share_links()            # list[ShareLink]

All other operations (download, preview, thumbnail, metadata, suggestions, more-like, email) are service-only — there are no model-level shortcuts for these:

downloaded  = await paperless.documents.download(doc.id)
preview     = await paperless.documents.preview(doc.id)
thumbnail   = await paperless.documents.thumbnail(doc.id)
meta        = await paperless.documents.metadata(doc.id)
suggestions = await paperless.documents.suggestions(doc.id)
async for similar in paperless.documents.more_like(doc.id):
    print(similar.title)
await paperless.documents.email(doc.id, addresses="alice@example.com", subject="Fwd", message="")

Permissions

async with paperless.documents.with_permissions():
    doc = await paperless.documents(42)
    print(doc.owner)        # owner user id
    print(doc.permissions)  # Permissions

Note

For downloading, searching, note management, and more, see Documents. To filter documents by custom field values, see Custom Field Query.