feat: add optional priority to upload metadata

[tiborrr]

---

Summary

• Add optional priority field (high | low) to upload meta JSON (ItemUploadMeta)
• Allow API clients and the webapp to set processing priority per upload
• Document the field in OpenAPI, upload docs, and Changelog

Motivation

I have to migrate a few thousand documents to Docspell, but do not want to clog the upload queue.

Upload priority was previously fixed by endpoint:

Endpoint	Default priority
Authenticated (/api/v1/sec/upload/item)	high
Open source URL (/api/v1/open/upload/item/{sourceId})	Source’s configured priority
Integration (/api/v1/open/integration/item/{collective})	Server config

There was no way to set priority per request. This adds per-upload control while keeping existing defaults when priority is omitted.

Changes

Backend

• Extend OUpload.UploadMeta with priority: Option[Priority]
• readMultipart: use meta.priority when set, otherwise endpoint default
• Open uploads via source: meta.priority overrides source default when provided

Webapp

• Priority dropdown on upload form (defaults to High)
• Sends priority in upload metadata

Docs / API

• OpenAPI: priority on ItemUploadMeta
• Upload API docs updated
• Changelog entry under Unreleased

API example

curl -XPOST \
  -H "X-Docspell-Auth: …" \
  -F 'meta={"multiple":true,"priority":"low"}' \
  -F file=@invoice.pdf \
  http://localhost:7880/api/v1/sec/upload/item

Backward compatibility

Fully backward compatible. Omitted priority keeps current behavior on all endpoints.

Manual verification

Tested locally against sbt reStart (H2, collective ets, user ets/admin) via /api/v1/sec/upload/item:

Upload	meta.priority	Job priority	Result
2026-04-15_AT2600707.pdf	(omitted)	High	success (~1s)
2026-04-15_AT2600723.pdf	"low"	Low	success (~1s)
2026-04-15_AT2600725.pdf	"high"	High	success (~1s)

All three returned {"success":true,"message":"Files submitted."}. Queue UI and joex logs matched expected priorities (process-item/High vs process-item/Low). DB job records: priority 10 (high) for default and explicit high; 0 (low) for explicit low.

Default secured upload without priority correctly uses high.

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request