Tags

Tags are labels that can be applied to documents for classification and filtering. They support the full CRUD lifecycle and permission management.

Models

See pypaperless/models/tags.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

tag = await paperless.tags(5)
print(tag.name)            # "Invoice"
print(tag.color)           # "#a6cee3"
print(tag.document_count)  # 38

Iterate

async for tag in paperless.tags:
    print(tag.id, tag.name, tag.color)

# Find the inbox tag
inbox = next(
    (t async for t in paperless.tags if t.is_inbox_tag),
    None,
)

Create

draft = paperless.tags.create()
draft.name = "Invoice"
draft.color = "#a6cee3"
draft.is_inbox_tag = False

pk = await paperless.tags.save(draft)
print(pk)  # primary key of the new tag

Update

tag = await paperless.tags(5)
tag.color = "#ff0000"
changed = await paperless.tags.update(tag)

Delete

tag = await paperless.tags(5)
await paperless.tags.delete(tag)

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

Permissions

async with paperless.tags.with_permissions():
    tag = await paperless.tags(5)
    print(tag.owner)        # owner user id
    print(tag.permissions)  # Permissions

See Permissions for details.