v2.4.0-Stable· 64 endpoints · 18 resource groups

REST API Reference

Resource-oriented URLs. JSON-encoded responses. Standard HTTP codes, authentication, and verbs. All endpoints are prefixed with /api/v1.

API Conventions

Base path	/api/v1/
Authentication	Authorization: Bearer <JWT> on all non-public endpoints
Content type	application/json for bodies; multipart/form-data for file uploads
Pagination	page (1-based) + size query params → { items, total, page, page_size, pages }
Error format	{ "detail": "<message>" } with appropriate HTTP status codes
Soft deletes	DELETE performs soft-delete (deleted=true); data remains in DB
Timestamps	ISO 8601 UTC format on all datetime fields
IDs	All resource IDs are 64-bit integers
API explorer	Swagger UI: /api/docs · ReDoc: /api/redoc · OpenAPI JSON: /api/openapi.json

Authentication Header

# All non-PUBLIC endpoints require this header Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... # Obtained via ZITADEL OAuth 2.0 PKCE flow # Service accounts: exchange ZITADEL JSON key for JWT

Pagination Envelope

{ "items": [...], "total": 142, "page": 1, "page_size": 20, "pages": 8 }

Endpoint Reference

favorite

Health

2 endpoints

Method	Path	Role	Description
GET	/api/v1/health	PUBLIC	Liveness probe — returns {"status":"ok"} if process is alive
GET	/api/v1/health/ready	PUBLIC	Readiness probe — checks DB, Redis, and MinIO connectivity; returns per-service status

lock_open

Authentication

4 endpoints

Method	Path	Role	Description
POST	/api/v1/auth/callback	Any	Called after OIDC callback; upserts user record from JWT claims; returns user profile
GET	/api/v1/auth/me	Any	Return the current authenticated user's profile
PUT	/api/v1/auth/me	Any	Update the current user's profile (display name, avatar, etc.)
POST	/api/v1/auth/logout	Any	Record logout audit event; clears server-side session state

description

Documents

16 endpoints

Method	Path	Role	Description
GET	/api/v1/documents	Any	List documents (paginated, org-scoped). Query: page, size, folder_id
POST	/api/v1/documents	Any	Create a document metadata record (file upload is a separate step)
GET	/api/v1/documents/starred	Any	List the current user's starred documents (paginated)
GET	/api/v1/documents/{id}	Any	Get a single document by ID, including AI fields and star status
PUT	/api/v1/documents/{id}	Any	Update document metadata (title, description, type, folder, tags, etc.)
DELETE	/api/v1/documents/{id}	Any	Soft-delete a document (MinIO object preserved; admin-recoverable)
PATCH	/api/v1/documents/{id}/status	Any	Transition document to a new status value (validated server-side)
POST	/api/v1/documents/{id}/upload	Any	Upload file content (multipart/form-data); creates a new version
GET	/api/v1/documents/{id}/download	Any	Return a presigned MinIO download URL (valid 15 minutes)
POST	/api/v1/documents/{id}/lock	Any	Claim exclusive write-lock. Returns 409 Conflict if already locked by another user
POST	/api/v1/documents/{id}/unlock	Any	Release the write-lock (document owner or ADMIN)
POST	/api/v1/documents/{id}/star	Any	Bookmark a document for the current user
DELETE	/api/v1/documents/{id}/star	Any	Remove a bookmark
GET	/api/v1/documents/{id}/retention	Any	Get retention status: retention_until, days_remaining, status (none/active/expired)
PUT	/api/v1/documents/{id}/retention	ADMIN	Set or update the retention_until date
DELETE	/api/v1/documents/{id}/retention	ADMIN	Clear the retention date

folder

Folders

8 endpoints

Method	Path	Role	Description
GET	/api/v1/folders	Any	List root folders for the organization (paginated)
POST	/api/v1/folders	Any	Create a new folder
GET	/api/v1/folders/{id}	Any	Get a folder by ID
PUT	/api/v1/folders/{id}	Any	Update folder metadata (name, description)
DELETE	/api/v1/folders/{id}	Any	Soft-delete folder and all descendants recursively
GET	/api/v1/folders/{id}/children	Any	List immediate child folders (paginated)
POST	/api/v1/folders/{id}/move	Any	Move folder to a new parent; rejects moves that would create a cycle
GET	/api/v1/folders/{id}/path	Any	Get the full breadcrumb path from root to this folder

manage_search

Search

2 endpoints

Method	Path	Role	Description
GET	/api/v1/search	Any	Full-text search (PostgreSQL tsvector). Params: q, folder_id, status, document_type, page, size
GET	/api/v1/search/semantic	Any	Semantic vector similarity search (pgvector cosine distance). Params: q, limit

account_tree

Workflows

5 endpoints

Method	Path	Role	Description
POST	/api/v1/workflows	Any	Create one approval workflow per document in document_ids list
GET	/api/v1/workflows/{id}	Any	Get a workflow with all its steps and current state
POST	/api/v1/workflows/{id}/steps/{step_id}/approve	Any	Approve a workflow step with an optional comment
POST	/api/v1/workflows/{id}/steps/{step_id}/reject	Any	Reject a workflow step with a mandatory reason
DELETE	/api/v1/workflows/{id}	Any	Cancel a workflow entirely

chat_bubble

Comments

7 endpoints

Method	Path	Role	Description
GET	/api/v1/comments/document/{document_id}	Any	List all comments for a document (threaded, with nested replies)
POST	/api/v1/comments	Any	Create a comment on a document (requires READ permission on document)
PUT	/api/v1/comments/{id}	Any	Update a comment (author only)
DELETE	/api/v1/comments/{id}	Any	Delete a comment (author or ADMIN)
POST	/api/v1/comments/{id}/resolve	Any	Resolve/close a comment thread (document owner or ADMIN)
POST	/api/v1/comments/{id}/react	Any	Add an emoji reaction to a comment
DELETE	/api/v1/comments/{id}/react	Any	Remove an emoji reaction

label

Method	Path	Role	Description
GET	/api/v1/tags	Any	List all tags for the organization
POST	/api/v1/tags	Any	Create a new tag
GET	/api/v1/tags/{id}	Any	Get a single tag
PUT	/api/v1/tags/{id}	Any	Update a tag
DELETE	/api/v1/tags/{id}	Any	Delete a tag
GET	/api/v1/tags/autocomplete	Any	Tag autocomplete suggestions. Param: q
GET	/api/v1/documents/{id}/tags	Any	Get all tags assigned to a document
POST	/api/v1/documents/{id}/tags	Any	Assign one or more tags to a document
DELETE	/api/v1/documents/{id}/tags	Any	Remove one or more tags from a document

Permissions

8 endpoints

Method	Path	Role	Description
GET	/api/v1/permissions/document/{doc_id}	Any	List all permission grants on a document
GET	/api/v1/permissions/folder/{folder_id}	Any	List all permission grants on a folder
POST	/api/v1/permissions/document	Any	Grant a permission on a document to a user or department
POST	/api/v1/permissions/folder	Any	Grant a permission on a folder to a user or department
PUT	/api/v1/permissions/{id}	Any	Update the permission level of an existing grant
DELETE	/api/v1/permissions/{id}	Any	Revoke a permission grant (soft delete)
GET	/api/v1/permissions/my/document/{doc_id}	Any	Get the current user's effective permission level on a document
GET	/api/v1/permissions/my/folder/{folder_id}	Any	Get the current user's effective permission level on a folder

Share Links

3 endpoints

Method	Path	Role	Description
POST	/api/v1/share-links	Any	Create a share link. Body: document_id, expires_at, password (optional), allowed_email (optional)
GET	/api/v1/share-links/{token}	PUBLIC	Validate a share token and return document access metadata. Direct DB lookup — never cached
DELETE	/api/v1/share-links/{id}	Any	Deactivate a share link

notifications

Notifications

3 endpoints

Method	Path	Role	Description
GET	/api/v1/notifications	Any	List the current user's notifications (paginated). Params: page, size
GET	/api/v1/notifications/unread-count	Any	Return the count of unread notifications
POST	/api/v1/notifications/{id}/read	Any	Mark a notification as read

domain

Organizations

4 endpoints

Method	Path	Role	Description
GET	/api/v1/organizations/me	Any	Get the current user's organization profile
GET	/api/v1/organizations/me/stats	Any	Dashboard statistics: document count, workflow count, user count, storage bytes
PUT	/api/v1/organizations/me	ADMIN	Update organization profile (name, logo, timezone, feature flags)
GET	/api/v1/organizations	SUPER_ADMIN	List all organizations on the platform

group

Users

5 endpoints

Method	Path	Role	Description
GET	/api/v1/users	MANAGER+	List users in the organization (paginated). Params: page, page_size, q (search)
GET	/api/v1/users/{id}	Any	Get a user profile by ID
PUT	/api/v1/users/{id}/role	ADMIN	Update a user's system role
POST	/api/v1/users/{id}/deactivate	ADMIN	Deactivate a user account (preserves all data and audit history)
POST	/api/v1/users/{id}/activate	ADMIN	Re-activate a previously deactivated user

mail

Invitations

3 endpoints

Method	Path	Role	Description
POST	/api/v1/users/invite	ADMIN	Create and send an invitation email. Body: email, role, department_id (optional)
GET	/api/v1/invitations/{token}	PUBLIC	Validate an invitation token and return its metadata (used by signup page)
POST	/api/v1/invitations/{token}/use	PUBLIC	Consume an invitation token; associate it with the newly registered user

corporate_fare

Departments

5 endpoints

Method	Path	Role	Description
GET	/api/v1/departments	Any	List all departments in the organization
POST	/api/v1/departments	ADMIN	Create a new department
GET	/api/v1/departments/{id}	Any	Get a department by ID
PUT	/api/v1/departments/{id}	ADMIN	Update department name or description
DELETE	/api/v1/departments/{id}	ADMIN	Delete a department

psychology

AI

2 endpoints

Method	Path	Role	Description
GET	/api/v1/ai/documents/{id}	Any	Retrieve stored AI fields: classification, summary, keywords, entities, chunk_index_status
POST	/api/v1/ai/reindex/{id}	Any	Queue document for AI reprocessing; resets ai_processed and sets chunk_index_status to QUEUED

forum

Chat (Document Q&A)

2 endpoints

Method	Path	Role	Description
POST	/api/v1/chat/document/{id}	Any	Stream a RAG Q&A response against document content via SSE. Body: message, session_id (optional to resume)
GET	/api/v1/chat/sessions	Any	List the current user's chat sessions. Params: scope_type, scope_id

swap_horiz

WebSocket

1 endpoint

Method	Path	Role	Description
WS	/api/v1/ws/{document_id}?token=<jwt>	JWT	Real-time collaboration channel: presence join/leave, cursor updates, lock state changes

Data Models

Document Object

{ "id": 1042, "title": "Q4 Financial Report", "file_name": "q4-2025-financials.pdf", "file_size_bytes": 2048000, "mime_type": "application/pdf", "status": "APPROVED", // DRAFT|IN_REVIEW|PENDING_APPROVAL|APPROVED|PUBLISHED|ARCHIVED "document_type": "FINANCIAL", "owner_id": 5, "organization_id": 2, "department_id": 8, "folder_id": 17, "current_version_number": 3, "view_count": 24, "download_count": 6, "comment_count": 4, "page_count": 18, "word_count": 4200, "checksum": "a3f2b1...", // SHA-256 for tamper detection "retention_until": "2027-12-31T23:59:59Z", "is_locked": false, "locked_by_id": null, "is_starred": true, "tags": ["finance", "Q4", "board"], "ai_processed": true, "ai_classification": "FINANCIAL_REPORT", "ai_confidence": 0.97, "ai_summary": "Quarterly financial results showing 18% revenue growth...", "ai_keywords": ["revenue", "Q4", "board"], "ai_entities": { "people": [...], "organizations": [...], "dates": [...] }, "chunk_index_status": "INDEXED", // NOT_INDEXED|QUEUED|INDEXED|FAILED "chunk_indexed_at": "2026-01-15T10:32:00Z", "created_at": "2026-01-14T09:00:00Z", "updated_at": "2026-01-15T11:00:00Z" }

Permission Grant Object

{ "id": 301, "permission_type": "WRITE", // NONE|READ|DOWNLOAD|COMMENT|CONTRIBUTOR|WRITE|EDITOR|ADMIN "resource_type": "document", // "document" or "folder" "resource_id": 1042, "user_id": 12, "department_id": null, // grant to dept: all current + future members inherit "expires_at": "2026-06-30T23:59:59Z", // null = permanent "created_at": "2026-01-10T08:00:00Z" }

Workflow Object

{ "id": 88, "document_id": 1042, "status": "IN_PROGRESS", "created_by_id": 5, "created_at": "2026-01-15T12:00:00Z", "steps": [ { "id": 201, "step_number": 1, "assignee_id": 9, "status": "APPROVED", "comment": "Looks good.", "decided_at": "2026-01-16T09:30:00Z" }, { "id": 202, "step_number": 2, "assignee_id": 3, "status": "PENDING", "comment": null, "decided_at": null } ] }

Share Link Object

{ "id": 55, "token": "sl_abc123xyz", "document_id": 1042, "created_by_id": 5, "expires_at": "2026-02-01T23:59:59Z", "is_password_protected": true, "allowed_email": null, // null = any email; set to restrict to one address "access_count": 3, "is_active": true, "created_at": "2026-01-15T14:00:00Z" }

Real-Time Protocols

WSWebSocket — Collaboration

Authenticated using the same OIDC JWT as REST API calls (passed as query param).

ws://host/api/v1/ws/{document_id}?token=<jwt> // Events received: { "type": "presence_join", "user_id": 12, "display_name": "Sarah K." } { "type": "presence_leave", "user_id": 12 } { "type": "cursor", "user_id": 12, "position": { "x": 420, "y": 220 } } { "type": "lock_acquired", "locked_by_id": 12 } { "type": "lock_released" }

SSEServer-Sent Events — Document Q&A

The chat endpoint streams LLM responses token-by-token. Enables progressive UI rendering without long-polling.

POST /api/v1/chat/document/{id} { "message": "What are the key findings?", "session_id": null } // SSE stream response: data: {"type": "token", "content": "The"} data: {"type": "token", "content": " contract"} data: {"type": "token", "content": " was signed"} ... data: {"type": "done", "session_id": 42, "citations": [...], "token_count": 87}

File Downloads — Presigned URLs

File bytes never flow through the VyXlo API server. The download endpoint returns a 15-minute presigned MinIO URL. The client fetches the file directly from object storage, which scales to very large files without API server memory pressure.

GET /api/v1/documents/1042/download Authorization: Bearer <access_token> // Response: { "url": "https://minio.example.com/bucket/q4-financials.pdf?X-Amz-Expires=900...", "expires_in": 900 } // Client fetches directly from MinIO — zero API server bandwidth

Resource Groups

Health2
Authentication4
Documents16
Folders8
Search2
Workflows5
Comments7
Tags9
Permissions8
Share Links3
Notifications3
Organizations4
Users5
Invitations3
Departments5
AI2
Chat (Document Q&A)2
WebSocket1

Live Explorer

Swagger UI available on your deployment

/api/docs

API Conventions

Authentication Header

Pagination Envelope

Endpoint Reference

Health

Authentication

Documents

Folders

Search

Workflows

Comments

Tags

Permissions

Share Links

Notifications

Organizations

Users

Invitations

Departments

AI

Chat (Document Q&A)

WebSocket

Data Models

Document Object

Permission Grant Object

Workflow Object

Share Link Object

Real-Time Protocols

WSWebSocket — Collaboration

SSEServer-Sent Events — Document Q&A

File Downloads — Presigned URLs

Sections

Resource Groups