Documents

Every document belongs to a category. Categories are scheme-specific, but a set of system categories is seeded for every new scheme and cannot be deleted:

Committees can add custom categories. All categories have a is_system flag.

Each document has an access_level that controls who can view it. Access is additive — a higher-privilege role sees all levels below its own:

The API enforces access level filtering on every list and detail request. The computedaccessible_levels for the caller's role is used to filter the query server-side.

When a document is superseded, the new version sets supersedes_document_id to the previous document's ID. The old document has is_current_version set to false.

• The document list endpoint returns only current versions by default (?current_only=true).
• The version history for a document is retrievable via GET .../documents/:id/versions.
• The version field is an integer, incrementing from 1.
• Superseding a document does not delete the old version — it remains accessible to users with the appropriate access level.

Documents have an is_published flag. Unpublished documents are visible only to committee members and above. Publishing makes the document visible to all members at or above its access level.

• Meeting notices are auto-published when issued (is_published: true).
• Minutes are typically uploaded as draft, reviewed, then published after confirmation at the next meeting.
• Any committee member can publish or unpublish a document.

Documents are stored in Supabase Storage. The upload flow:

1. Client requests a signed upload URL via POST /api/schemes/:id/documents/upload-url.
2. Client uploads the file directly to Supabase Storage using the signed URL.
3. Client confirms the upload via POST /api/schemes/:id/documents with metadata.

Download links are short-lived signed URLs (1-hour expiry) generated on each detail or list request.

Allowed file types:

Other MIME types return HTTP 422.

A document can be linked to a meeting via the optional meeting_id field. Meeting notices created automatically by the issue-notice endpoint are linked in this way. The meeting detail endpoint does not inline documents — query the document list with?meeting_id= to retrieve all documents attached to a meeting.

• Full document history is available on every plan — there is no free tier or history cap.
• Document writes (upload, edit, publish) are blocked only when a scheme is past its trial without payment (status expired), returning HTTP 402 until billing is set up. Storage is subject to Supabase project limits.