Trash

The trash resource exposes documents that have been soft-deleted in Paperless-ngx. Trashed documents can be restored or permanently deleted. The service iterates over Document objects just like the main documents service.

Model

Trashed documents use the same Document model - see pypaperless/models/documents/document.py and pypaperless/models/types.py for enum and filter types. In the trash context, deleted_at is additionally populated with the timestamp when the document was moved to the trash.

Iterate

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

# Collect all trashed documents as a list
trashed = await paperless.trash.as_list()
print(f"{len(trashed)} document(s) in trash")

Filter

/api/trash/ declares no query filters. filter() therefore only accepts the pagination parameters, and passing document filters has no effect — the endpoint silently returns the full trash:

# Only page / page_size are honoured here
async with paperless.trash.filter(page_size=25) as ctx:
    async for doc in ctx:
        print(doc.id, doc.title)

Narrow the result set client-side instead:

trashed = await paperless.trash.as_list()
invoices = [doc for doc in trashed if "invoice" in (doc.title or "").lower()]

Restore

Restore one or more documents back to the document archive:

await paperless.trash.restore([42, 43])

Empty

Permanently delete documents from the trash. Pass a list of IDs to delete specific documents, or call without arguments to empty the entire trash:

# Delete specific documents permanently
await paperless.trash.empty([42, 43])

# Empty the entire trash
await paperless.trash.empty()