clusterzx / paperless-ai
5,643 JavaScriptAn automated document analyzer for Paperless-ngx using OpenAI API, Ollama, Deepseek-r1, Azure and all OpenAI API compatible Services to automatically analyze and tag your documents.
Paperless-AI API Documentation Specification
Located in OPENAPI/openapi.json on branch HEAD
3.0.0
JSON
36 Endpoints
126.1 KB
Operations & Route Endpoints (39)
Raw JSON Specification
{
"openapi": "3.0.0",
"info": {
"title": "Paperless-AI API Documentation",
"version": "1.0.0",
"description": "API documentation for the Paperless-AI application",
"license": {
"name": "MIT",
"url": "https://opensource.org/licenses/MIT"
},
"contact": {
"name": "Clusterzx",
"url": "https://github.com/Clusterzx"
}
},
"servers": [
{
"url": "http://localhost:3000",
"description": "Development server"
}
],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "JWT-based authentication for web app users. The token is obtained by authenticating via the login endpoint.\n\n### How to authenticate:\n1. Send a POST request to `/login` with your username and password\n2. The server will respond with a JWT token (also set as a cookie in browsers)\n3. Include this token in the `Authorization` header as `Bearer {token}`\n\nExample:\n```\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\n```\n\nJWT tokens are valid for 24 hours after issuance.\n"
},
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "x-api-key",
"description": "API key authentication for programmatic access. The API key can be generated or regenerated using the /api/key-regenerate endpoint.\n\n### How to authenticate:\n1. Access the API key from your application settings\n2. Include the API key in the `x-api-key` HTTP header for all requests\n\nExample:\n```\nx-api-key: 7c1f3f5e2b0a9d8c6e4b2a1d3f5e8c9b2a1d3f5e\n```\n\nAPI keys do not expire unless regenerated.\n"
}
},
"schemas": {
"Error": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error message",
"example": "Error resetting documents"
}
}
},
"User": {
"type": "object",
"required": [
"username",
"password"
],
"properties": {
"username": {
"type": "string",
"description": "User's username",
"example": "admin"
},
"password": {
"type": "string",
"format": "password",
"description": "User's password (will be hashed)",
"example": "securePassword123"
},
"id": {
"type": "integer",
"description": "User ID (auto-generated)",
"example": 1,
"readOnly": true
}
}
},
"Document": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Document ID",
"example": 123
},
"title": {
"type": "string",
"description": "Document title",
"example": "Invoice"
},
"tags": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Array of tag IDs",
"example": [
1,
4,
7
]
},
"correspondent": {
"type": "integer",
"description": "Correspondent ID",
"example": 5
},
"created": {
"type": "string",
"format": "date-time",
"description": "Document creation date",
"example": "2023-12-15T10:30:00Z"
},
"document_type": {
"type": "integer",
"description": "Document type ID",
"example": 2
},
"content": {
"type": "string",
"description": "Document text content",
"example": "This is an invoice from Company XYZ..."
},
"language": {
"type": "string",
"description": "Document language code",
"example": "en"
},
"custom_fields": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomField"
},
"description": "Custom field values for the document"
}
}
},
"HistoryItem": {
"type": "object",
"properties": {
"document_id": {
"type": "integer",
"description": "Document ID",
"example": 123
},
"title": {
"type": "string",
"description": "Document title",
"example": "Invoice"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Date and time when the processing occurred",
"example": "2023-12-15T10:30:00Z"
},
"tags": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Tag"
}
},
"correspondent": {
"type": "string",
"description": "Document correspondent name",
"example": "Acme Corp"
},
"link": {
"type": "string",
"description": "Link to the document in Paperless-ngx",
"example": "http://paperless.example.com/documents/123/"
}
}
},
"Tag": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Tag ID",
"example": 5
},
"name": {
"type": "string",
"description": "Tag name",
"example": "Invoice"
},
"color": {
"type": "string",
"description": "Tag color (hex code)",
"example": "#FF5733"
},
"match": {
"type": "string",
"enum": [
"ANY",
"ALL",
"LITERAL",
"REGEX"
],
"description": "Tag matching algorithm",
"example": "ANY"
}
}
},
"LoginRequest": {
"type": "object",
"required": [
"username",
"password"
],
"properties": {
"username": {
"type": "string",
"description": "User's username",
"example": "admin"
},
"password": {
"type": "string",
"format": "password",
"description": "User's password",
"example": "securePassword123"
}
}
},
"LoginResponse": {
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "JWT token for authentication",
"example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
},
"expiresIn": {
"type": "string",
"description": "Token expiration time",
"example": "24h"
}
}
},
"DocumentUpdateRequest": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "New document title",
"example": "Updated Invoice"
},
"tags": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Array of tag IDs",
"example": [
1,
4,
7
]
},
"correspondent": {
"type": "integer",
"description": "Correspondent ID",
"example": 5
},
"document_type": {
"type": "integer",
"description": "Document type ID",
"example": 2
},
"language": {
"type": "string",
"description": "Document language code",
"example": "en"
},
"custom_fields": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomField"
},
"description": "Custom field values for the document"
}
}
},
"CustomField": {
"type": "object",
"required": [
"field",
"value"
],
"properties": {
"field": {
"type": "integer",
"description": "Custom field ID",
"example": 3
},
"value": {
"type": "string",
"description": "Custom field value",
"example": "123.45"
}
}
},
"AnalysisResult": {
"type": "object",
"properties": {
"document": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Suggested document title",
"example": "Invoice from ABC Corporation"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Suggested tags",
"example": [
"invoice",
"utilities",
"2023"
]
},
"correspondent": {
"type": "string",
"description": "Suggested correspondent name",
"example": "ABC Corporation"
},
"document_type": {
"type": "string",
"description": "Suggested document type",
"example": "Invoice"
},
"document_date": {
"type": "string",
"format": "date-time",
"description": "Extracted document date",
"example": "2023-12-15T00:00:00Z"
},
"language": {
"type": "string",
"description": "Detected document language",
"example": "en"
},
"custom_fields": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"field_name": {
"type": "string",
"description": "Custom field name",
"example": "invoice_amount"
},
"value": {
"type": "string",
"description": "Custom field value",
"example": "123.45"
}
}
}
}
}
},
"metrics": {
"type": "object",
"properties": {
"promptTokens": {
"type": "integer",
"description": "Number of tokens in the prompt",
"example": 450
},
"completionTokens": {
"type": "integer",
"description": "Number of tokens in the completion",
"example": 120
},
"totalTokens": {
"type": "integer",
"description": "Total tokens used",
"example": 570
}
}
},
"error": {
"type": "string",
"description": "Error message if analysis failed",
"example": null
}
}
},
"HistoryResponse": {
"type": "object",
"properties": {
"draw": {
"type": "integer",
"description": "DataTables draw counter echo",
"example": 1
},
"recordsTotal": {
"type": "integer",
"description": "Total number of records in database",
"example": 100
},
"recordsFiltered": {
"type": "integer",
"description": "Number of records after filtering",
"example": 25
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HistoryItem"
}
}
}
},
"ChatMessage": {
"type": "object",
"required": [
"documentId",
"message"
],
"properties": {
"documentId": {
"type": "integer",
"description": "ID of the document the chat is about",
"example": 123
},
"message": {
"type": "string",
"description": "User's message to the AI",
"example": "What is the invoice amount?"
}
}
},
"ChatInitResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Whether initialization was successful",
"example": true
},
"message": {
"type": "string",
"description": "Status message",
"example": "Chat initialized for document 123"
}
}
},
"APIKeyResponse": {
"type": "object",
"properties": {
"success": {
"type": "string",
"description": "The newly generated API key",
"example": "7c1f3f5e2b0a9d8c6e4b2a1d3f5e8c9b2a1d3f5e"
}
}
},
"HealthResponse": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"healthy",
"not_configured",
"error"
],
"description": "System health status",
"example": "healthy"
},
"message": {
"type": "string",
"description": "Additional status information (for non-healthy states)",
"example": "Application setup not completed"
}
}
}
}
},
"security": [
{
"BearerAuth": []
},
{
"ApiKeyAuth": []
}
],
"paths": {
"/api-docs/openapi.json": {
"get": {
"summary": "Retrieve the OpenAPI specification",
"description": "Returns the complete OpenAPI specification for the Paperless-AI API.\nThis endpoint attempts to serve a static OpenAPI JSON file first, falling back\nto dynamically generating the specification if the file cannot be read.\n\nThe OpenAPI specification document contains all API endpoints, parameters,\nrequest bodies, responses, and schemas for the entire application.\n",
"tags": [
"API",
"System"
],
"responses": {
"200": {
"description": "OpenAPI specification returned successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "The complete OpenAPI specification"
}
}
}
},
"404": {
"description": "OpenAPI specification file not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error occurred while retrieving the OpenAPI specification",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/": {
"get": {
"summary": "Root endpoint that redirects to the dashboard",
"description": "This endpoint serves as the entry point for the application.\nWhen accessed, it automatically redirects the user to the dashboard page.\nNo parameters or authentication are required for this redirection.\n",
"tags": [
"Navigation",
"System"
],
"responses": {
"302": {
"description": "Redirects to the dashboard page",
"content": {
"text/html": {
"schema": {
"type": "string",
"example": "<html><body>Redirecting to dashboard...</body></html>"
}
}
}
},
"500": {
"description": "Server error occurred during redirection",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/health": {
"get": {
"summary": "System health check endpoint",
"description": "Provides information about the current system health status.\nThis endpoint checks database connectivity and returns system operational status.\nUsed for monitoring and automated health checks.\n",
"tags": [
"System"
],
"responses": {
"200": {
"description": "System is healthy and operational",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "healthy",
"description": "Health status of the system"
}
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Status indicating an error",
"example": "error"
},
"message": {
"type": "string",
"description": "Error message details",
"example": "Internal server error"
}
}
}
}
}
},
"503": {
"description": "Service unavailable",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"not_configured",
"error"
],
"example": "database_error",
"description": "Status indicating database error"
},
"message": {
"type": "string",
"example": "Database check failed",
"description": "Details about the service unavailability"
}
}
}
}
}
}
}
}
},
"/login": {
"get": {
"summary": "Render login page or redirect to setup if no users exist",
"description": "Serves the login page for user authentication to the Paperless-AI application.\nIf no users exist in the database, the endpoint automatically redirects to the setup page\nto complete the initial application configuration.\n\nThis endpoint handles both new user sessions and returning users whose\nsessions have expired.\n",
"tags": [
"Authentication",
"Navigation"
],
"responses": {
"200": {
"description": "Login page rendered successfully",
"content": {
"text/html": {
"schema": {
"type": "string",
"description": "HTML content of the login page"
}
}
}
},
"302": {
"description": "Redirect to setup page if no users exist, or to dashboard if already authenticated",
"headers": {
"Location": {
"schema": {
"type": "string",
"example": "/setup"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"summary": "Authenticate user with username and password",
"description": "Authenticates a user using their username and password credentials.\nIf authentication is successful, a JWT token is generated and stored in a secure HTTP-only\ncookie for subsequent requests.\n\nFailed login attempts are logged for security purposes, and multiple failures\nmay result in temporary account lockout depending on configuration.\n",
"tags": [
"Authentication"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"username",
"password"
],
"properties": {
"username": {
"type": "string",
"description": "User's login name",
"example": "admin"
},
"password": {
"type": "string",
"description": "User's password",
"example": "securepassword"
},
"rememberMe": {
"type": "boolean",
"description": "Whether to extend the session lifetime",
"example": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "Authentication successful",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"redirect": {
"type": "string",
"description": "URL to redirect to after successful login",
"example": "/dashboard"
}
}
}
}
},
"headers": {
"Set-Cookie": {
"schema": {
"type": "string",
"description": "HTTP-only cookie containing JWT token"
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"message": {
"type": "string",
"example": "Invalid username or password"
}
}
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/logout": {
"get": {
"summary": "Log out user and clear JWT cookie",
"description": "Terminates the current user session by invalidating and clearing the JWT authentication\ncookie. After logging out, the user is redirected to the login page.\n\nThis endpoint also clears any session-related data stored on the server side\nfor the current user.\n",
"tags": [
"Authentication"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"302": {
"description": "Logout successful, redirected to login page",
"headers": {
"Location": {
"schema": {
"type": "string",
"example": "/login"
}
},
"Set-Cookie": {
"schema": {
"type": "string",
"description": "HTTP-only cookie with cleared JWT token and immediate expiration"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/sampleData/{id}": {
"get": {
"summary": "Get sample data for a document",
"description": "Retrieves sample data extracted from a document, including processed text content\nand any metadata that has been extracted or processed by the AI.\n\nThis endpoint is commonly used for previewing document data in the UI before\ncompleting document processing or updating metadata.\n",
"tags": [
"Documents",
"API"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
},
"description": "Document ID to retrieve sample data for",
"example": 123
}
],
"responses": {
"200": {
"description": "Document sample data retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "Extracted text content from the document",
"example": "Invoice from Acme Corp. Total amount: $125.00, Due date: 2023-08-15"
},
"metadata": {
"type": "object",
"description": "Any metadata that has been extracted from the document",
"properties": {
"title": {
"type": "string",
"example": "Acme Corp Invoice - August 2023"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"Invoice",
"Finance"
]
},
"correspondent": {
"type": "string",
"example": "Acme Corp"
}
}
}
}
}
}
}
},
"404": {
"description": "Document not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Document not found"
}
}
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/playground": {
"get": {
"summary": "AI playground testing environment",
"description": "Renders the AI playground page for experimenting with document analysis.\n\nThis interactive environment allows users to test different AI providers and prompts\non document content without affecting the actual document processing workflow.\nUsers can paste document text, customize prompts, and see raw AI responses\nto better understand how the AI models analyze document content.\n\nThe playground is useful for fine-tuning prompts and testing AI capabilities\nbefore applying them to actual document processing.\n",
"tags": [
"Navigation",
"Documents"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Playground page rendered successfully",
"content": {
"text/html": {
"schema": {
"type": "string",
"description": "HTML content of the AI playground interface"
}
}
}
},
"401": {
"description": "Unauthorized - user not authenticated",
"headers": {
"Location": {
"schema": {
"type": "string",
"example": "/login"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/thumb/{documentId}": {
"get": {
"summary": "Get document thumbnail",
"description": "Retrieves the thumbnail image for a specific document from the Paperless-ngx system.\nThis endpoint proxies the request to the Paperless-ngx API and returns the thumbnail\nimage for display in the UI.\n\nThe thumbnail is returned as an image file in the format provided by Paperless-ngx,\ntypically JPEG or PNG.\n",
"tags": [
"Documents",
"API"
],
"security": [
{
"BearerAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "documentId",
"required": true,
"schema": {
"type": "integer"
},
"description": "ID of the document to retrieve thumbnail for",
"example": 123
}
],
"responses": {
"200": {
"description": "Thumbnail retrieved successfully",
"content": {
"image/*": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"404": {
"description": "Document or thumbnail not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Thumbnail not found"
}
}
}
}
}
},
"500": {
"description": "Server error or Paperless-ngx connection failure",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/chat": {
"get": {
"summary": "Chat interface page",
"description": "Renders the chat interface page where users can interact with document-specific AI assistants.\nThis page displays a list of available documents and the chat interface for the selected document.\n",
"tags": [
"Navigation",
"Chat"
],
"parameters": [
{
"in": "query",
"name": "open",
"schema": {
"type": "string"
},
"description": "ID of document to open immediately in chat",
"required": false
}
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Chat interface page rendered successfully",
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Invalid or expired token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/chat/init": {
"get": {
"summary": "Initialize chat for a document via query parameter",
"description": "Initializes a chat session for a specific document identified by the query parameter.\nLoads document content and prepares it for the chat interface.\nThis endpoint returns the document content, chat history if available, and initial context.\n",
"tags": [
"API",
"Chat"
],
"parameters": [
{
"in": "query",
"name": "documentId",
"required": true,
"schema": {
"type": "string"
},
"description": "ID of the document to initialize chat for",
"example": "123"
}
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Chat session initialized successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"description": "ID of the document",
"example": "123"
},
"content": {
"type": "string",
"description": "Content of the document",
"example": "This is the document content"
},
"title": {
"type": "string",
"description": "Title of the document",
"example": "Invoice #12345"
},
"history": {
"type": "array",
"description": "Previous chat messages if any",
"items": {
"type": "object",
"properties": {
"role": {
"type": "string",
"example": "user"
},
"content": {
"type": "string",
"example": "What is this document about?"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Missing document ID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Invalid or expired token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Document not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/chat/message": {
"post": {
"summary": "Send message to document chat",
"description": "Sends a user message to the document-specific chat AI assistant.\nThe message is processed in the context of the specified document.\nReturns a streaming response with the AI's reply chunks.\n",
"tags": [
"API",
"Chat"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"documentId",
"message"
],
"properties": {
"documentId": {
"type": "string",
"description": "ID of the document to chat with",
"example": "123"
},
"message": {
"type": "string",
"description": "User message to send to the chat",
"example": "What is this document about?"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Response streaming started. Each event contains a message chunk.\n",
"content": {
"text/event-stream": {
"schema": {
"type": "string",
"example": "data: {\"chunk\":\"This document appears to be\"}\n\ndata: {\"chunk\":\" an invoice from\"}\n\ndata: {\"done\":true}\n"
}
}
}
},
"400": {
"description": "Missing document ID or message",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Invalid or expired token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Document not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/chat/init/{documentId}": {
"get": {
"summary": "Initialize chat for a document via path parameter",
"description": "Initializes a chat session for a specific document identified by the path parameter.\nLoads document content and prepares it for the chat interface.\nThis endpoint returns the document content, chat history if available, and initial context.\n",
"tags": [
"API",
"Chat"
],
"parameters": [
{
"in": "path",
"name": "documentId",
"required": true,
"schema": {
"type": "string"
},
"description": "ID of the document to initialize chat for",
"example": "123"
}
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Chat session initialized successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"description": "ID of the document",
"example": "123"
},
"content": {
"type": "string",
"description": "Content of the document",
"example": "This is the document content"
},
"title": {
"type": "string",
"description": "Title of the document",
"example": "Invoice #12345"
},
"history": {
"type": "array",
"description": "Previous chat messages if any",
"items": {
"type": "object",
"properties": {
"role": {
"type": "string",
"example": "user"
},
"content": {
"type": "string",
"example": "What is this document about?"
}
}
}
}
}
}
}
}
},
"400": {
"description": "Missing document ID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Invalid or expired token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Document not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/history": {
"get": {
"summary": "Document history page",
"description": "Renders the document history page with filtering options.\nThis page displays a list of all documents that have been processed by Paperless-AI,\nshowing the changes made to the documents through AI processing.\n\nThe page includes filtering capabilities by correspondent, tag, and free text search,\nallowing users to easily find specific documents or categories of processed documents.\nEach entry includes links to the original document in Paperless-ngx.\n",
"tags": [
"History",
"Navigation"
],
"security": [
{
"BearerAuth": []
},
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "History page rendered successfully",
"content": {
"text/html": {
"schema": {
"type": "string",
"description": "HTML content of the history page with filtering controls and document list"
}
}
}
},
"401": {
"description": "Unauthorized - user not authenticated",
"headers": {
"Location": {
"schema": {
"type": "string",
"example": "/login"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/history": {
"get": {
"summary": "Get processed document history",
"description": "Returns a paginated list of documents that have been processed by Paperless-AI.\nSupports filtering by tag, correspondent, and search term.\nDesigned for integration with DataTables jQuery plugin.\n\nThis endpoint provides comprehensive information about each processed document,\nincluding its metadata before and after AI processing, allowing users to track\nchanges made by the system.\n",
"tags": [
"History",
"API"
],
"security": [
{
"BearerAuth": []
},
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"in": "query",
"name": "draw",
"schema": {
"type": "integer"
},
"description": "Draw counter for DataTables (prevents XSS)",
"example": 1
},
{
"in": "query",
"name": "start",
"schema": {
"type": "integer",
"default": 0
},
"description": "Starting record index for pagination",
"example": 0
},
{
"in": "query",
"name": "length",
"schema": {
"type": "integer",
"default": 10
},
"description": "Number of records to return per page",
"example": 10
},
{
"in": "query",
"name": "search[value]",
"schema": {
"type": "string"
},
"description": "Global search term (searches title, correspondent and tags)",
"example": "invoice"
},
{
"in": "query",
"name": "tag",
"schema": {
"type": "string"
},
"description": "Filter by tag ID",
"example": "5"
},
{
"in": "query",
"name": "correspondent",
"schema": {
"type": "string"
},
"description": "Filter by correspondent name",
"example": "Acme Corp"
},
{
"in": "query",
"name": "order[0][column]",
"schema": {
"type": "integer"
},
"description": "Index of column to sort by (0=document_id, 1=title, etc.)",
"example": 1
},
{
"in": "query",
"name": "order[0][dir]",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
]
},
"description": "Sort direction (ascending or descending)",
"example": "desc"
}
],
"responses": {
"200": {
"description": "Document history returned successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"draw": {
"type": "integer",
"description": "Echo of the draw parameter",
"example": 1
},
"recordsTotal": {
"type": "integer",
"description": "Total number of records in the database",
"example": 100
},
"recordsFiltered": {
"type": "integer",
"description": "Number of records after filtering",
"example": 20
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"document_id": {
"type": "integer",
"description": "Document ID",
"example": 123
},
"title": {
"type": "string",
"description": "Document title",
"example": "Invoice #12345"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Date and time when the processing occurred",
"example": "2023-07-15T14:30:45Z"
},
"tags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 5
},
"name": {
"type": "string",
"example": "Invoice"
},
"color": {
"type": "string",
"example": "#FF5733"
}
}
}
},
"correspondent": {
"type": "string",
"description": "Document correspondent name",
"example": "Acme Corp"
},
"link": {
"type": "string",
"description": "Link to the document in Paperless-ngx",
"example": "http://paperless.example.com/documents/123/"
}
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized - authentication required",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Authentication required"
}
}
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Error loading history data"
}
}
}
}
}
}
}
}
},
"/api/reset-all-documents": {
"post": {
"summary": "Reset all processed documents",
"description": "Deletes all processing records from the database, allowing documents to be processed again.\nThis doesn't delete the actual documents from Paperless-ngx, only their processing status in Paperless-AI.\n\nThis operation can be useful when changing AI models or prompts, as it allows reprocessing\nall documents with the updated configuration.\n",
"tags": [
"Documents",
"API"
],
"security": [
{
"BearerAuth": []
},
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "All documents successfully reset",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
}
}
}
}
}
},
"401": {
"description": "Unauthorized - authentication required",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Authentication required"
}
}
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Error resetting documents"
}
}
}
}
}
}
}
}
},
"/api/reset-documents": {
"post": {
"summary": "Reset specific documents",
"description": "Deletes processing records for specific documents, allowing them to be processed again.\nThis doesn't delete the actual documents from Paperless-ngx, only their processing status in Paperless-AI.\n\nThis operation is useful when you want to reprocess only selected documents after changes to\nthe AI model, prompt, or document metadata configuration.\n",
"tags": [
"Documents",
"API"
],
"security": [
{
"BearerAuth": []
},
{
"ApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ids"
],
"properties": {
"ids": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Array of document IDs to reset",
"example": [
123,
456,
789
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Documents successfully reset",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
}
}
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Invalid document IDs"
}
}
}
}
}
},
"401": {
"description": "Unauthorized - authentication required",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Authentication required"
}
}
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Error resetting documents"
}
}
}
}
}
}
}
}
},
"/api/scan/now": {
"post": {
"summary": "Trigger immediate document scan",
"description": "Initiates an immediate scan of documents in Paperless-ngx that haven't been processed yet.\nThis endpoint can be used to manually trigger processing without waiting for the scheduled interval.\n\nThe scan will:\n- Connect to Paperless-ngx API\n- Fetch all unprocessed documents\n- Process each document with the configured AI service\n- Update documents in Paperless-ngx with generated metadata\n\nThe process respects the function limitations set in the configuration.\n",
"tags": [
"Documents",
"API"
],
"security": [
{
"BearerAuth": []
},
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Scan initiated successfully",
"content": {
"text/plain": {
"schema": {
"type": "string",
"example": "Task completed"
}
}
}
},
"401": {
"description": "Unauthorized - authentication required",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Authentication required"
}
}
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Error during document scan"
}
}
}
}
}
}
}
}
},
"/api/key-regenerate": {
"post": {
"summary": "Regenerate API key",
"description": "Generates a new random API key for the application and updates the .env file.\nThe previous API key will be invalidated immediately after generation.\n\nThis API key can be used for programmatic access to the API endpoints\nby sending it in the `x-api-key` header of subsequent requests.\n\n**Security Notice**: This operation invalidates any existing API key.\nAll systems using the previous key will need to be updated.\n",
"tags": [
"System",
"Authentication"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "API key regenerated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "string",
"description": "The newly generated API key",
"example": "3f7a8d6e2c1b5a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5"
}
}
}
}
}
},
"401": {
"description": "Unauthorized - JWT authentication required",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Authentication required"
}
}
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Error regenerating API key"
}
}
}
}
}
}
}
}
},
"/setup": {
"get": {
"summary": "Application setup page",
"description": "Renders the application setup page for initial configuration.\n\nThis page allows configuring the connection to Paperless-ngx, AI services,\nand other application settings. It loads existing configuration if available\nand redirects to dashboard if setup is already complete.\n\nThe setup page is the entry point for new installations and guides users through\nthe process of connecting to Paperless-ngx, configuring AI providers, and setting up\nadmin credentials.\n",
"tags": [
"Navigation",
"Setup",
"System"
],
"responses": {
"200": {
"description": "Setup page rendered successfully",
"content": {
"text/html": {
"schema": {
"type": "string",
"description": "HTML content of the application setup page"
}
}
}
},
"302": {
"description": "Redirects to dashboard if setup is already complete",
"headers": {
"Location": {
"schema": {
"type": "string",
"example": "/dashboard"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"summary": "Submit initial application setup configuration",
"description": "Configures the initial setup of the Paperless-AI application, including connections\nto Paperless-ngx, AI provider settings, processing parameters, and user authentication.\n\nThis endpoint is primarily used during the first-time setup of the application and\ncreates the necessary configuration files and database tables.\n",
"tags": [
"System",
"Setup"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"paperlessUrl",
"paperlessToken",
"aiProvider",
"username",
"password"
],
"properties": {
"paperlessUrl": {
"type": "string",
"description": "URL of the Paperless-ngx instance",
"example": "https://paperless.example.com"
},
"paperlessToken": {
"type": "string",
"description": "API token for Paperless-ngx access",
"example": "abc123def456"
},
"paperlessUsername": {
"type": "string",
"description": "Username for Paperless-ngx (alternative to token authentication)",
"example": "admin"
},
"aiProvider": {
"type": "string",
"description": "Selected AI provider for document analysis",
"enum": [
"openai",
"ollama",
"custom",
"azure"
],
"example": "openai"
},
"openaiKey": {
"type": "string",
"description": "API key for OpenAI (required when aiProvider is 'openai')",
"example": "sk-abc123def456"
},
"openaiModel": {
"type": "string",
"description": "OpenAI model to use for analysis",
"example": "gpt-4"
},
"ollamaUrl": {
"type": "string",
"description": "URL for Ollama API (required when aiProvider is 'ollama')",
"example": "http://localhost:11434"
},
"ollamaModel": {
"type": "string",
"description": "Ollama model to use for analysis",
"example": "llama2"
},
"customApiKey": {
"type": "string",
"description": "API key for custom LLM provider",
"example": "api-key-123"
},
"customBaseUrl": {
"type": "string",
"description": "Base URL for custom LLM provider",
"example": "https://api.customllm.com"
},
"customModel": {
"type": "string",
"description": "Model name for custom LLM provider",
"example": "custom-model"
},
"scanInterval": {
"type": "number",
"description": "Interval in minutes for scanning new documents",
"example": 15
},
"systemPrompt": {
"type": "string",
"description": "Custom system prompt for document analysis",
"example": "Extract key information from the following document..."
},
"showTags": {
"type": "boolean",
"description": "Whether to show tags in the UI",
"example": true
},
"tags": {
"type": "string",
"description": "Comma-separated list of tags to use for filtering",
"example": "Invoice,Receipt,Contract"
},
"aiProcessedTag": {
"type": "boolean",
"description": "Whether to add a tag for AI-processed documents",
"example": true
},
"aiTagName": {
"type": "string",
"description": "Tag name to use for AI-processed documents",
"example": "AI-Processed"
},
"usePromptTags": {
"type": "boolean",
"description": "Whether to use tags in prompts",
"example": true
},
"promptTags": {
"type": "string",
"description": "Comma-separated list of tags to use in prompts",
"example": "Invoice,Receipt"
},
"username": {
"type": "string",
"description": "Admin username for Paperless-AI",
"example": "admin"
},
"password": {
"type": "string",
"description": "Admin password for Paperless-AI",
"example": "securepassword"
},
"useExistingData": {
"type": "boolean",
"description": "Whether to use existing data from a previous setup",
"example": false
},
"activateTagging": {
"type": "boolean",
"description": "Enable AI-based tag suggestions",
"example": true
},
"activateCorrespondents": {
"type": "boolean",
"description": "Enable AI-based correspondent suggestions",
"example": true
},
"activateDocumentType": {
"type": "boolean",
"description": "Enable AI-based document type suggestions",
"example": true
},
"activateTitle": {
"type": "boolean",
"description": "Enable AI-based title suggestions",
"example": true
},
"activateCustomFields": {
"type": "boolean",
"description": "Enable AI-based custom field extraction",
"example": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "Setup completed successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success"
],
"example": "success"
},
"message": {
"type": "string",
"example": "Configuration saved successfully"
}
}
}
}
}
},
"400": {
"description": "Invalid configuration parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"error"
],
"example": "error"
},
"message": {
"type": "string",
"example": "Missing required configuration parameters"
}
}
}
}
}
},
"500": {
"description": "Server error during setup",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"error"
],
"example": "error"
},
"message": {
"type": "string",
"example": "Failed to save configuration: Database error"
}
}
}
}
}
}
}
}
},
"/manual/preview/{id}": {
"get": {
"summary": "Document preview",
"description": "Fetches and returns the content of a specific document from Paperless-ngx \nfor preview in the manual document review interface.\n\nThis endpoint retrieves document details including content, title, ID, and tags,\nallowing users to view the document text before applying changes or processing\nit with AI tools. The document content is retrieved directly from Paperless-ngx\nusing the system's configured API credentials.\n",
"tags": [
"Documents",
"API"
],
"security": [
{
"BearerAuth": []
},
{
"ApiKeyAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "integer"
},
"description": "The document ID from Paperless-ngx",
"example": 123
}
],
"responses": {
"200": {
"description": "Document content retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "The document content",
"example": "Invoice from ACME Corp. Amount: $1,234.56"
},
"title": {
"type": "string",
"description": "The document title",
"example": "ACME Corp Invoice #12345"
},
"id": {
"type": "integer",
"description": "The document ID",
"example": 123
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of tag names assigned to the document",
"example": [
"Invoice",
"ACME Corp",
"2023"
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized - user not authenticated",
"headers": {
"Location": {
"schema": {
"type": "string",
"example": "/login"
}
}
}
},
"404": {
"description": "Document not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error or Paperless connection error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/manual": {
"get": {
"summary": "Document review page",
"description": "Renders the manual document review page that allows users to browse, \nview and manually process documents from Paperless-ngx.\n\nThis interface enables users to review documents, view their content, and \nmanage tags, correspondents, and document metadata without AI assistance.\nUsers can apply manual changes to documents based on their own judgment,\nwhich is particularly useful for correction or verification of AI-processed documents.\n",
"tags": [
"Navigation",
"Documents"
],
"security": [
{
"BearerAuth": []
},
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Manual document review page rendered successfully",
"content": {
"text/html": {
"schema": {
"type": "string",
"description": "HTML content of the manual document review interface"
}
}
}
},
"401": {
"description": "Unauthorized - user not authenticated",
"headers": {
"Location": {
"schema": {
"type": "string",
"example": "/login"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/manual/tags": {
"get": {
"summary": "Get all tags",
"description": "Retrieves all tags from Paperless-ngx for use in the manual document review interface.\n\nThis endpoint returns a complete list of all available tags that can be applied to documents,\nincluding their IDs, names, and colors. The tags are retrieved directly from Paperless-ngx\nand used for tag selection in the UI when manually updating document metadata.\n",
"tags": [
"Documents",
"API",
"Metadata"
],
"security": [
{
"BearerAuth": []
},
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Tags retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Tag"
}
}
}
}
},
"401": {
"description": "Unauthorized - user not authenticated",
"headers": {
"Location": {
"schema": {
"type": "string",
"example": "/login"
}
}
}
},
"500": {
"description": "Server error or Paperless connection error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/manual/documents": {
"get": {
"summary": "Get all documents",
"description": "Retrieves all documents from Paperless-ngx for display in the manual document review interface.\n\nThis endpoint returns a list of all available documents that can be manually reviewed,\nincluding their basic metadata such as ID, title, and creation date. The documents are\nretrieved directly from Paperless-ngx and presented in the UI for selection and processing.\n",
"tags": [
"Documents",
"API"
],
"security": [
{
"BearerAuth": []
},
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Documents retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Document"
}
}
}
}
},
"401": {
"description": "Unauthorized - user not authenticated",
"headers": {
"Location": {
"schema": {
"type": "string",
"example": "/login"
}
}
}
},
"500": {
"description": "Server error or Paperless connection error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/correspondentsCount": {
"get": {
"summary": "Get count of correspondents",
"description": "Retrieves the list of correspondents with their document counts.\nThis endpoint returns all correspondents in the system along with \nthe number of documents associated with each correspondent.\n",
"tags": [
"API",
"Metadata"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "List of correspondents with document counts retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "ID of the correspondent",
"example": 1
},
"name": {
"type": "string",
"description": "Name of the correspondent",
"example": "ACME Corp"
},
"count": {
"type": "integer",
"description": "Number of documents associated with this correspondent",
"example": 5
}
}
}
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Invalid or expired token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/tagsCount": {
"get": {
"summary": "Get count of tags",
"description": "Retrieves the list of tags with their document counts.\nThis endpoint returns all tags in the system along with \nthe number of documents associated with each tag.\n",
"tags": [
"API",
"Metadata"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "List of tags with document counts retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "ID of the tag",
"example": 1
},
"name": {
"type": "string",
"description": "Name of the tag",
"example": "Invoice"
},
"count": {
"type": "integer",
"description": "Number of documents associated with this tag",
"example": 12
}
}
}
}
}
}
},
"401": {
"description": "Authentication required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Invalid or expired token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/webhook/document": {
"post": {
"summary": "Webhook for document updates",
"description": "Processes incoming webhook notifications from Paperless-ngx about document\nchanges, additions, or deletions. The webhook allows Paperless-AI to respond\nto document changes in real-time.\n\nWhen a new document is added or updated in Paperless-ngx, this endpoint can\ntrigger automatic AI processing for metadata extraction.\n",
"tags": [
"Documents",
"API",
"System"
],
"security": [
{
"ApiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"event_type",
"document_id"
],
"properties": {
"event_type": {
"type": "string",
"description": "Type of event that occurred",
"enum": [
"added",
"updated",
"deleted"
],
"example": "added"
},
"document_id": {
"type": "integer",
"description": "ID of the affected document",
"example": 123
},
"document_info": {
"type": "object",
"description": "Additional information about the document (optional)",
"properties": {
"title": {
"type": "string",
"example": "Invoice"
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Webhook processed successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Document event processed"
},
"processing_queued": {
"type": "boolean",
"description": "Whether AI processing was queued for this document",
"example": true
}
}
}
}
}
},
"400": {
"description": "Invalid webhook payload",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false
},
"error": {
"type": "string",
"example": "Missing required fields: event_type, document_id"
}
}
}
}
}
},
"401": {
"description": "Unauthorized - invalid or missing API key",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Unauthorized: Invalid API key"
}
}
}
}
}
},
"500": {
"description": "Server error processing webhook",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/dashboard": {
"get": {
"summary": "Main dashboard page",
"description": "Renders the main dashboard page of the application with summary statistics and visualizations.\nThe dashboard provides an overview of processed documents, system metrics, and important statistics\nabout document processing including tag counts, correspondent counts, and token usage.\n\nThe page displays visualizations for document processing status, token distribution, \nprocessing time statistics, and document type categorization to help administrators\nunderstand system performance and document processing patterns.\n",
"tags": [
"Navigation",
"System"
],
"security": [
{
"BearerAuth": []
},
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Dashboard page rendered successfully",
"content": {
"text/html": {
"schema": {
"type": "string",
"description": "HTML content of the dashboard page"
}
}
}
},
"401": {
"description": "Unauthorized - user not authenticated",
"headers": {
"Location": {
"schema": {
"type": "string",
"example": "/login"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/settings": {
"get": {
"summary": "Application settings page",
"description": "Renders the application settings page where users can modify configuration\nafter initial setup.\n\nThis page allows administrators to update connections to Paperless-ngx, \nAI provider settings, processing parameters, feature toggles, and custom fields.\nThe interface provides validation for connection settings and displays the current\nconfiguration values.\n\nChanges made on this page require application restart to take full effect.\n",
"tags": [
"Navigation",
"Setup",
"System"
],
"security": [
{
"BearerAuth": []
},
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Settings page rendered successfully",
"content": {
"text/html": {
"schema": {
"type": "string",
"description": "HTML content of the application settings page"
}
}
}
},
"401": {
"description": "Unauthorized - user not authenticated",
"headers": {
"Location": {
"schema": {
"type": "string",
"example": "/login"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"summary": "Update application settings",
"description": "Updates the configuration settings of the Paperless-AI application after initial setup.\nThis endpoint allows administrators to modify connections to Paperless-ngx, \nAI provider settings, processing parameters, and feature toggles.\n\nChanges made through this endpoint are applied immediately and affect all future\ndocument processing operations.\n",
"tags": [
"System",
"Setup"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"paperlessUrl": {
"type": "string",
"description": "URL of the Paperless-ngx instance",
"example": "https://paperless.example.com"
},
"paperlessToken": {
"type": "string",
"description": "API token for Paperless-ngx access",
"example": "abc123def456"
},
"paperlessUsername": {
"type": "string",
"description": "Username for Paperless-ngx (alternative to token authentication)",
"example": "admin"
},
"aiProvider": {
"type": "string",
"description": "Selected AI provider for document analysis",
"enum": [
"openai",
"ollama",
"custom",
"azure"
],
"example": "openai"
},
"openaiKey": {
"type": "string",
"description": "API key for OpenAI (required when aiProvider is 'openai')",
"example": "sk-abc123def456"
},
"openaiModel": {
"type": "string",
"description": "OpenAI model to use for analysis",
"example": "gpt-4"
},
"ollamaUrl": {
"type": "string",
"description": "URL for Ollama API (required when aiProvider is 'ollama')",
"example": "http://localhost:11434"
},
"ollamaModel": {
"type": "string",
"description": "Ollama model to use for analysis",
"example": "llama2"
},
"customApiKey": {
"type": "string",
"description": "API key for custom LLM provider",
"example": "api-key-123"
},
"customBaseUrl": {
"type": "string",
"description": "Base URL for custom LLM provider",
"example": "https://api.customllm.com"
},
"customModel": {
"type": "string",
"description": "Model name for custom LLM provider",
"example": "custom-model"
},
"scanInterval": {
"type": "number",
"description": "Interval in minutes for scanning new documents",
"example": 15
},
"systemPrompt": {
"type": "string",
"description": "Custom system prompt for document analysis",
"example": "Extract key information from the following document..."
},
"showTags": {
"type": "boolean",
"description": "Whether to show tags in the UI",
"example": true
},
"tokenLimit": {
"type": "integer",
"description": "The maximum number of tokens th AI can handle",
"example": 128000
},
"responseTokens": {
"type": "integer",
"description": "The approx. amount of tokens required for the response",
"example": 1000
},
"tags": {
"type": "string",
"description": "Comma-separated list of tags to use for filtering",
"example": "Invoice,Receipt,Contract"
},
"aiProcessedTag": {
"type": "boolean",
"description": "Whether to add a tag for AI-processed documents",
"example": true
},
"aiTagName": {
"type": "string",
"description": "Tag name to use for AI-processed documents",
"example": "AI-Processed"
},
"usePromptTags": {
"type": "boolean",
"description": "Whether to use tags in prompts",
"example": true
},
"promptTags": {
"type": "string",
"description": "Comma-separated list of tags to use in prompts",
"example": "Invoice,Receipt"
},
"useExistingData": {
"type": "boolean",
"description": "Whether to use existing data from a previous setup",
"example": false
},
"activateTagging": {
"type": "boolean",
"description": "Enable AI-based tag suggestions",
"example": true
},
"activateCorrespondents": {
"type": "boolean",
"description": "Enable AI-based correspondent suggestions",
"example": true
},
"activateDocumentType": {
"type": "boolean",
"description": "Enable AI-based document type suggestions",
"example": true
},
"activateTitle": {
"type": "boolean",
"description": "Enable AI-based title suggestions",
"example": true
},
"activateCustomFields": {
"type": "boolean",
"description": "Enable AI-based custom field extraction",
"example": false
},
"customFields": {
"type": "string",
"description": "JSON string defining custom fields to extract",
"example": "{\"invoice_number\":{\"type\":\"string\"},\"total_amount\":{\"type\":\"number\"}}"
},
"disableAutomaticProcessing": {
"type": "boolean",
"description": "Disable automatic document processing",
"example": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "Settings updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"success"
],
"example": "success"
},
"message": {
"type": "string",
"example": "Settings updated successfully"
}
}
}
}
}
},
"400": {
"description": "Invalid configuration parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"error"
],
"example": "error"
},
"message": {
"type": "string",
"example": "Invalid settings: AI provider required when automatic processing is enabled"
}
}
}
}
}
},
"500": {
"description": "Server error while updating settings",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"error"
],
"example": "error"
},
"message": {
"type": "string",
"example": "Failed to update settings: Database error"
}
}
}
}
}
}
}
}
},
"/debug": {
"get": {
"summary": "Debug interface",
"description": "Renders a debug interface for testing and troubleshooting Paperless-ngx connections\nand API responses.\n\nThis page provides a simple UI for executing API calls to Paperless-ngx endpoints\nand viewing the raw responses. It's primarily used for diagnosing connection issues\nand understanding the structure of data returned by the Paperless-ngx API.\n\nThe debug interface should only be accessible to administrators and is not intended\nfor regular use in production environments.\n",
"tags": [
"Navigation",
"System"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Debug interface rendered successfully",
"content": {
"text/html": {
"schema": {
"type": "string",
"description": "HTML content of the debug interface"
}
}
}
},
"401": {
"description": "Unauthorized - user not authenticated",
"headers": {
"Location": {
"schema": {
"type": "string",
"example": "/login"
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/debug/tags": {
"get": {
"summary": "Debug tags API",
"description": "Returns the raw tags data from Paperless-ngx for debugging purposes.\n\nThis endpoint performs a direct API call to the Paperless-ngx tags endpoint\nand returns the unmodified response. It's used for diagnosing tag-related issues\nand verifying proper connection to Paperless-ngx.\n",
"tags": [
"System",
"API",
"Metadata"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Tags data retrieved successfully from Paperless-ngx",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Raw response from Paperless-ngx tags API"
}
}
}
},
"401": {
"description": "Unauthorized - user not authenticated",
"headers": {
"Location": {
"schema": {
"type": "string",
"example": "/login"
}
}
}
},
"500": {
"description": "Server error or Paperless connection error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/debug/documents": {
"get": {
"summary": "Debug documents API",
"description": "Returns the raw documents data from Paperless-ngx for debugging purposes.\n\nThis endpoint performs a direct API call to the Paperless-ngx documents endpoint\nand returns the unmodified response. It's used for diagnosing document-related issues\nand verifying proper connection to Paperless-ngx.\n",
"tags": [
"System",
"API",
"Documents"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Documents data retrieved successfully from Paperless-ngx",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Raw response from Paperless-ngx documents API"
}
}
}
},
"401": {
"description": "Unauthorized - user not authenticated",
"headers": {
"Location": {
"schema": {
"type": "string",
"example": "/login"
}
}
}
},
"500": {
"description": "Server error or Paperless connection error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/debug/correspondents": {
"get": {
"summary": "Debug correspondents API",
"description": "Returns the raw correspondents data from Paperless-ngx for debugging purposes.\n\nThis endpoint performs a direct API call to the Paperless-ngx correspondents endpoint\nand returns the unmodified response. It's used for diagnosing correspondent-related issues\nand verifying proper connection to Paperless-ngx.\n",
"tags": [
"System",
"API",
"Metadata"
],
"security": [
{
"BearerAuth": []
}
],
"responses": {
"200": {
"description": "Correspondents data retrieved successfully from Paperless-ngx",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Raw response from Paperless-ngx correspondents API"
}
}
}
},
"401": {
"description": "Unauthorized - user not authenticated",
"headers": {
"Location": {
"schema": {
"type": "string",
"example": "/login"
}
}
}
},
"500": {
"description": "Server error or Paperless connection error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/manual/analyze": {
"post": {
"summary": "Analyze document content manually",
"description": "Analyzes document content using the configured AI provider and returns structured metadata.\nThis endpoint processes the document text to extract relevant information such as tags,\ncorrespondent, and document type based on content analysis.\n\nThe analysis is performed using the AI provider configured in the application settings.\n",
"tags": [
"Documents",
"API"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"type": "string",
"description": "The document text content to analyze",
"example": "Invoice from Acme Corp. Total amount: $125.00, Due date: 2023-08-15"
},
"existingTags": {
"type": "array",
"description": "List of existing tags in the system to help with tag matching",
"items": {
"type": "string"
},
"example": [
"Invoice",
"Finance",
"Acme Corp"
]
},
"id": {
"type": "string",
"description": "Optional document ID for tracking metrics",
"example": "doc_123"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Document analysis results",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"correspondent": {
"type": "string",
"description": "Detected correspondent name",
"example": "Acme Corp"
},
"title": {
"type": "string",
"description": "Suggested document title",
"example": "Acme Corp Invoice - August 2023"
},
"tags": {
"type": "array",
"description": "Suggested tags for the document",
"items": {
"type": "string"
},
"example": [
"Invoice",
"Finance"
]
},
"documentType": {
"type": "string",
"description": "Detected document type",
"example": "Invoice"
},
"metrics": {
"type": "object",
"description": "Token usage metrics (when using OpenAI)",
"properties": {
"promptTokens": {
"type": "number",
"example": 350
},
"completionTokens": {
"type": "number",
"example": 120
},
"totalTokens": {
"type": "number",
"example": 470
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error or AI provider not configured",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/manual/playground": {
"post": {
"summary": "Process document using a custom prompt in playground mode",
"description": "Analyzes document content using a custom user-provided prompt.\nThis endpoint is primarily used for testing and experimenting with different prompts\nwithout affecting the actual document processing workflow.\n\nThe analysis is performed using the AI provider configured in the application settings,\nbut with a custom prompt that overrides the default system prompt.\n",
"tags": [
"Documents",
"API"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"content"
],
"properties": {
"content": {
"type": "string",
"description": "The document text content to analyze",
"example": "Invoice from Acme Corp. Total amount: $125.00, Due date: 2023-08-15"
},
"prompt": {
"type": "string",
"description": "Custom prompt to use for analysis",
"example": "Extract the company name, invoice amount, and due date from this document."
},
"documentId": {
"type": "string",
"description": "Optional document ID for tracking metrics",
"example": "doc_123"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Document analysis results using the custom prompt",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"result": {
"type": "string",
"description": "The raw AI response using the custom prompt",
"example": "Company: Acme Corp\nAmount: $125.00\nDue Date: 2023-08-15"
},
"metrics": {
"type": "object",
"description": "Token usage metrics (when using OpenAI)",
"properties": {
"promptTokens": {
"type": "number",
"example": 350
},
"completionTokens": {
"type": "number",
"example": 120
},
"totalTokens": {
"type": "number",
"example": 470
}
}
}
}
}
}
}
},
"400": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Server error or AI provider not configured",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/manual/updateDocument": {
"post": {
"summary": "Update document metadata in Paperless-ngx",
"description": "Updates document metadata such as tags, correspondent and title in the Paperless-ngx system.\nThis endpoint handles the translation between tag names and IDs, and manages the creation of\nnew tags or correspondents if they don't exist in the system.\n\nThe endpoint also removes any unused tags from the document to keep the metadata clean.\n",
"tags": [
"Documents",
"API"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"documentId"
],
"properties": {
"documentId": {
"type": "number",
"description": "ID of the document to update in Paperless-ngx",
"example": 123
},
"tags": {
"type": "array",
"description": "List of tags to apply (can be tag IDs or names)",
"items": {
"oneOf": [
{
"type": "number"
},
{
"type": "string"
}
]
},
"example": [
"Invoice",
42,
"Finance"
]
},
"correspondent": {
"type": "string",
"description": "Correspondent name to assign to the document",
"example": "Acme Corp"
},
"title": {
"type": "string",
"description": "New title for the document",
"example": "Acme Corp Invoice - August 2023"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Document successfully updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": true
},
"message": {
"type": "string",
"example": "Document updated successfully"
}
}
}
}
}
},
"400": {
"description": "Invalid request parameters or tag processing errors",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"Failed to create tag: Invalid tag name"
]
}
}
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/processing-status": {
"get": {
"summary": "Get document processing status",
"description": "Returns the current status of document processing operations.\nThis endpoint provides information about documents in the processing queue\nand the current processing state (active/idle).\n\nThe status information can be used by UIs to display progress indicators\nand provide real-time feedback about background processing operations.\n",
"tags": [
"Documents",
"System",
"API"
],
"security": [
{
"BearerAuth": []
},
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Processing status retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"isProcessing": {
"type": "boolean",
"description": "Whether documents are currently being processed",
"example": true
},
"queueLength": {
"type": "integer",
"description": "Number of documents waiting in the processing queue",
"example": 5
},
"currentDocument": {
"type": "object",
"description": "Details about the document currently being processed (if any)",
"properties": {
"id": {
"type": "integer",
"description": "Document ID",
"example": 123
},
"title": {
"type": "string",
"description": "Document title",
"example": "Invoice #12345"
},
"status": {
"type": "string",
"description": "Current processing status",
"example": "processing"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized - authentication required",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Authentication required"
}
}
}
}
}
},
"500": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Failed to fetch processing status"
}
}
}
}
}
}
}
}
}
},
"tags": [
{
"name": "Authentication",
"description": "User authentication and authorization endpoints, including login, logout, and token management"
},
{
"name": "Documents",
"description": "Document management and processing endpoints for interacting with Paperless-ngx documents"
},
{
"name": "History",
"description": "Document processing history and tracking of AI-generated metadata"
},
{
"name": "Navigation",
"description": "General navigation endpoints for the web interface"
},
{
"name": "System",
"description": "System configuration, health checks, and administrative functions"
},
{
"name": "Chat",
"description": "Document chat functionality for interacting with document content using AI"
},
{
"name": "Setup",
"description": "Application setup and configuration endpoints"
},
{
"name": "Metadata",
"description": "Endpoints for managing document metadata like tags, correspondents, and document types"
}
]
}