### Install Dependencies and Start Development Mode

Source: https://github.com/clusterzx/paperless-ai/blob/main/README.md

Use these commands to install project dependencies and start the development server for local development.

```bash
npm install

npm run test
```

--------------------------------

### Clone Repository and Start with Docker Compose

Source: https://github.com/clusterzx/paperless-ai/wiki/2.-Installation

Use this method to clone the paperless-ai repository and then start the services using Docker Compose. Ensure Docker and Docker Compose are installed.

```bash
git clone https://github.com/clusterzx/paperless-ai.git
cd paperless-ai
docker-compose up -d
```

--------------------------------

### Setup Wizard

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Renders the initial setup wizard and processes submitted configuration for connecting to Paperless-ngx and an AI provider.

```APIDOC
## Setup & Configuration

### `GET /setup` and `POST /setup`

Renders the first-time setup wizard and processes the submitted configuration. On `POST`, the server validates connections to Paperless-ngx and the chosen AI provider, creates the `.env` configuration file under `data/`, hashes and stores the admin password in SQLite, then restarts the process after 5 seconds.

```bash
curl -X POST http://localhost:3000/setup \
  -H "Content-Type: application/json" \
  -d '{ 
    "paperlessUrl": "http://paperless.local:8000",
    "paperlessToken": "abc123",
    "paperlessUsername": "admin",
    "aiProvider": "openai",
    "openaiKey": "sk-...",
    "openaiModel": "gpt-4o-mini",
    "scanInterval": "*/30 * * * *",
    "systemPrompt": "You are a document analyzer...",
    "username": "admin",
    "password": "secret",
    "activateTagging": true,
    "activateCorrespondents": true,
    "activateDocumentType": true,
    "activateTitle": true,
    "activateCustomFields": false,
    "showTags": "no",
    "tokenLimit": 128000,
    "responseTokens": 1000
  }'
# { "success": true, "message": "Configuration saved successfully.", "restart": true }
```
```

--------------------------------

### Initial Setup Configuration

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Perform the initial setup of Paperless-AI by POSTing configuration details to the /setup endpoint. This validates connections, creates the .env file, stores credentials, and restarts the application.

```bash
curl -X POST http://localhost:3000/setup \
  -H "Content-Type: application/json" \
  -d '{ \
    "paperlessUrl": "http://paperless.local:8000", \
    "paperlessToken": "abc123", \
    "paperlessUsername": "admin", \
    "aiProvider": "openai", \
    "openaiKey": "sk-...", \
    "openaiModel": "gpt-4o-mini", \
    "scanInterval": "*/30 * * * *", \
    "systemPrompt": "You are a document analyzer...", \
    "username": "admin", \
    "password": "secret", \
    "activateTagging": true, \
    "activateCorrespondents": true, \
    "activateDocumentType": true, \
    "activateTitle": true, \
    "activateCustomFields": false, \
    "showTags": "no", \
    "tokenLimit": 128000, \
    "responseTokens": 1000 \
  }'
# { "success": true, "message": "Configuration saved successfully.", "restart": true }
```

--------------------------------

### Manual Installation for Paperless AI

Source: https://github.com/clusterzx/paperless-ai/blob/main/docs/index.html

Install Paperless AI manually by cloning the repository, installing dependencies, and running the main script. Ensure you have Python and pip installed.

```bash
git clone https://github.com/clusterzx/paperless-ai.git
cd paperless-ai
pip install -r requirements.txt
python main.py
```

--------------------------------

### Start Paperless-AI Application

Source: https://github.com/clusterzx/paperless-ai/blob/main/RAG-DEV-GUIDE.md

Start the main Paperless-AI application in development mode using npm. Ensure environment variables are set correctly beforehand.

```bash
npm run dev
```

--------------------------------

### Docker Deployment Commands

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Commands to manage the Paperless-AI Docker container: start in detached mode, follow logs, and access the initial setup wizard in a browser.

```bash
# Start the service
docker compose up -d

# View logs
docker compose logs -f paperless-ai

# First-time setup: open browser and complete the wizard
open http://localhost:3000/setup
```

--------------------------------

### Install Node.js and Python Dependencies

Source: https://github.com/clusterzx/paperless-ai/blob/main/RAG-DEV-GUIDE.md

Install necessary dependencies for both the Node.js frontend and the Python RAG backend. Ensure you have Node.js 16+ and Python 3.10+ installed.

```bash
# Install Node.js dependencies
npm install

# Install Python dependencies
pip install -r requirements.txt
```

--------------------------------

### Authentication Examples

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Demonstrates how to authenticate programmatic requests using an API key and the JWT login flow.

```APIDOC
## Authentication

### JWT and API Key middleware (`routes/auth.js`)

All routes except `/health`, `/login`, `/logout`, and `/setup` require authentication. Two methods are supported: a JWT cookie set at login (24-hour expiry) or a static API key passed as the `x-api-key` request header.

```js
// Authenticate programmatic requests using the API key
const response = await fetch('http://localhost:3000/api/history', {
  headers: {
    'x-api-key': 'your-api-key-from-env'
  }
});
const data = await response.json();
// { draw: 1, recordsTotal: 42, recordsFiltered: 42, data: [...] }

// JWT login flow
const loginRes = await fetch('http://localhost:3000/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username: 'admin', password: 'secret' })
});
// On success: HTTP 302 redirect to /dashboard; jwt cookie is set.
// On failure: renders login page with error: 'Invalid credentials'
```
```

--------------------------------

### Make and Run Services Script

Source: https://github.com/clusterzx/paperless-ai/blob/main/RAG-DEV-GUIDE.md

Make the `start-services.sh` script executable and then run it to start both the Node.js and Python services simultaneously. This is the recommended approach for development.

```bash
# Make the script executable first (Linux/macOS)
chmod +x start-services.sh

# Run the services
./start-services.sh
```

--------------------------------

### Path Parameter Documentation

Source: https://github.com/clusterzx/paperless-ai/blob/main/jsdoc_standards.md

Document path parameters with their name, type, required status, purpose, and an example value.

```javascript
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *         description: The resource ID
 *         example: 123
```

--------------------------------

### Start Python RAG Service

Source: https://github.com/clusterzx/paperless-ai/blob/main/RAG-DEV-GUIDE.md

Run the Python RAG service independently. Use the `--initialize` flag to build the document index on startup. Specify host and port if needed.

```python
python main.py --host 127.0.0.1 --port 8000 --initialize
```

--------------------------------

### Docker Installation for Paperless AI

Source: https://github.com/clusterzx/paperless-ai/blob/main/docs/index.html

Quickly set up Paperless AI using Docker. This command pulls the latest image and runs it as a detached container, mapping port 3000 and setting up persistent storage.

```bash
docker pull clusterzx/paperless-ai:latest

docker run -d \
    --name paperless-ai \
    --network bridge \
    -v paperless-ai_data:/app/data \
    -p 3000:3000 \
    --restart unless-stopped \
    clusterzx/paperless-ai
```

--------------------------------

### API Key Authentication Example

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Authenticate programmatic requests to the Paperless-AI API using an API key. Ensure the API key is securely stored and passed in the 'x-api-key' header.

```javascript
const response = await fetch('http://localhost:3000/api/history', {
  headers: {
    'x-api-key': 'your-api-key-from-env'
  }
});
const data = await response.json();
// { draw: 1, recordsTotal: 42, recordsFiltered: 42, data: [...] }
```

--------------------------------

### Minimal Production Docker Compose Setup

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Define a minimal `docker-compose.yml` for production, including service configuration, port mapping, and volume persistence for `/app/data`. Ensure `RAG_SERVICE_ENABLED` is set if using the RAG sidecar.

```yaml
# docker-compose.yml — minimal production setup
services:
  paperless-ai:
    image: clusterzx/paperless-ai
    container_name: paperless-ai
    restart: unless-stopped
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges=true
    environment:
      - PAPERLESS_AI_PORT=3000
      - RAG_SERVICE_URL=http://localhost:8000
      - RAG_SERVICE_ENABLED=true
    ports:
      - "3000:3000"
    volumes:
      - paperless-ai_data:/app/data

volumes:
  paperless-ai_data:
```

--------------------------------

### JWT Login Flow Example

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Initiate the JWT login flow by sending username and password to the /login endpoint. A successful login sets a JWT cookie for subsequent authenticated requests.

```javascript
// JWT login flow
const loginRes = await fetch('http://localhost:3000/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username: 'admin', password: 'secret' })
});
// On success: HTTP 302 redirect to /dashboard; jwt cookie is set.
// On failure: renders login page with error: 'Invalid credentials'
```

--------------------------------

### Defining Inline Response Schema

Source: https://github.com/clusterzx/paperless-ai/blob/main/jsdoc_standards.md

For simple responses, define the schema inline. Include the object type, properties with their types, descriptions, and example values.

```yaml
 *               schema:
 *                 type: object
 *                 properties:
 *                   success:
 *                     type: boolean
 *                     description: Whether the operation succeeded
 *                     example: true
```

--------------------------------

### Documenting Streaming Response

Source: https://github.com/clusterzx/paperless-ai/blob/main/jsdoc_standards.md

For streaming endpoints, document the 'text/event-stream' content type. Provide a schema example that illustrates the format of each data chunk and the termination signal.

```yaml
 *       200:
 *         description: |
 *           Response streaming started. Each event contains a message chunk.
 *         content:
 *           text/event-stream:
 *             schema:
 *               type: string
 *               example: |
 *                 data: {"chunk":"Example response chunk"}
 *                 
 *                 data: {"done":true}
```

--------------------------------

### Documenting Request Body Schema

Source: https://github.com/clusterzx/paperless-ai/blob/main/jsdoc_standards.md

Use this structure to document the request body for POST/PUT endpoints, specifying requirements, content type, and a detailed schema with properties and examples.

```yaml
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - propertyName
 *             properties:
 *               propertyName:
 *                 type: string
 *                 description: Description of the property
 *                 example: "Example value"
```

--------------------------------

### Get Document Preview

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Retrieves the raw text content, title, ID, and resolved tag names for a specific Paperless-ngx document. Used to populate manual review interfaces.

```APIDOC
## GET /manual/preview/:id

### Description
Returns the raw text content, title, ID, and resolved tag names for a Paperless-ngx document. Used to populate the manual review interface.

### Method
GET

### Endpoint
/manual/preview/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the document to preview.

### Request Example
```bash
curl http://localhost:3000/manual/preview/123 \
  -H "x-api-key: your-api-key"
```

### Response
#### Success Response
- **content** (string) - The raw text content of the document.
- **title** (string) - The title of the document.
- **id** (integer) - The ID of the document.
- **tags** (array) - An array of resolved tag names.

#### Response Example
```json
{
  "content": "INVOICE\nFrom: Acme Corp...",
  "title": "Acme Corp Invoice",
  "id": 123,
  "tags": ["Invoice", "Finance"]
}
```
```

--------------------------------

### Summary and Description in JSDoc

Source: https://github.com/clusterzx/paperless-ai/blob/main/jsdoc_standards.md

Endpoints require a concise summary and a detailed description using the pipe symbol for multi-line content. The description should explain purpose, functionality, side effects, and include usage examples if necessary.

```javascript
/**
 * @swagger
 * /api/example:
 *   get:
 *     summary: Brief description of what this endpoint does
 *     description: |
 *       Detailed explanation of the endpoint functionality.
 *       This should cover what the endpoint does, how it works,
 *       and any important behaviors users should know about.
 *       
 *       Use multiple paragraphs for complex explanations.
 */
```

--------------------------------

### Get Metadata Counts

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Retrieve counts of tags or correspondents from Paperless-ngx, used for dashboard charts.

```bash
curl http://localhost:3000/api/tagsCount -H "x-api-key: your-api-key"
```

```bash
curl http://localhost:3000/api/correspondentsCount -H "x-api-key: your-api-key"
```

--------------------------------

### Get Document Thumbnail

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Proxies and caches document thumbnail images from Paperless-ngx. Cached PNGs are stored in `public/images/`.

```APIDOC
## GET /thumb/:documentId

### Description
Proxies and caches document thumbnail images from Paperless-ngx. Cached PNGs are stored in `public/images/`.

### Method
GET

### Endpoint
/thumb/:documentId

### Parameters
#### Path Parameters
- **documentId** (string) - Required - The ID of the document for which to retrieve the thumbnail.

### Request Example
```bash
curl http://localhost:3000/thumb/123 \
  -H "x-api-key: your-api-key" \
  --output thumbnail.png
```

### Response
#### Success Response
Returns PNG image data for the document thumbnail.
```

--------------------------------

### Configure Paperless-NGX Credentials

Source: https://github.com/clusterzx/paperless-ai/blob/main/RAG-DEV-GUIDE.md

Set up your Paperless-NGX instance URL and API token in the `.env` file located in the `data` directory. The Python service also reads API settings from this file.

```dotenv
PAPERLESS_API_URL=https://your-paperless-ngx-instance
PAPERLESS_API_TOKEN=your-api-token
```

--------------------------------

### Security Requirements in JSDoc

Source: https://github.com/clusterzx/paperless-ai/blob/main/jsdoc_standards.md

Protected endpoints must specify security requirements using BearerAuth or ApiKeyAuth. This example shows how to include both.

```javascript
 *     security:
 *       - BearerAuth: []
 *       - ApiKeyAuth: []
```

--------------------------------

### Get Processing Status

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Returns real-time information about the document currently being processed, the last completed document, and the total count processed today.

```bash
curl http://localhost:3000/api/processing-status \
  -H "x-api-key: your-api-key"
```

--------------------------------

### Parameters Documentation

Source: https://github.com/clusterzx/paperless-ai/blob/main/jsdoc_standards.md

Guidelines for documenting path and query parameters for API endpoints.

```APIDOC
## 5. Parameters Documentation

### 5.1 Path Parameters

Path parameters should be documented with:
- Parameter name matching the path definition
- Schema type (integer, string, etc.)
- Required flag (almost always true for path parameters)
- Description of the parameter purpose
- Example value

```javascript
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *         description: The resource ID
 *         example: 123
```

### 5.2 Query Parameters

Query parameters follow a similar format but include:
- Default values where applicable
- Enumerated values if the parameter has a restricted set of options

```javascript
 *     parameters:
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 10
 *         description: Maximum number of records to return
```
```

--------------------------------

### Get Processing Status

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Returns real-time information about the document currently being processed, the last completed document, and the total count processed today.

```APIDOC
## GET /api/processing-status

### Description
Returns real-time information about the document currently being processed, the last completed document, and the total count processed today.

### Method
GET

### Endpoint
/api/processing-status

### Request Example
```bash
curl http://localhost:3000/api/processing-status \
  -H "x-api-key: your-api-key"
```

### Response
#### Success Response
- **currentlyProcessing** (object) - Information about the document currently being processed.
  - **documentId** (integer) - The ID of the document.
  - **title** (string) - The title of the document.
  - **startTime** (string) - The start time of processing.
  - **status** (string) - The current status (e.g., "processing").
- **lastProcessed** (object) - Information about the last processed document.
  - **documentId** (integer) - The ID of the document.
  - **title** (string) - The title of the document.
  - **processed_at** (string) - The timestamp when it was processed.
- **processedToday** (integer) - The total number of documents processed today.
- **isProcessing** (boolean) - Indicates if any document is currently being processed.

#### Response Example
```json
{
  "currentlyProcessing": {
    "documentId": 45,
    "title": "Electricity Bill Q1",
    "startTime": "2024-03-15T10:22:01",
    "status": "processing"
  },
  "lastProcessed": { "documentId": 44, "title": "Bank Statement Feb", "processed_at": "2024-03-15T10:21:58" },
  "processedToday": 12,
  "isProcessing": true
}
```
```

--------------------------------

### Process Document via Webhook

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Accepts a Paperless-ngx document URL to queue it for AI processing. An optional custom prompt can override the default system prompt for a single document. Register this in Paperless-ngx post_consume_script or webhook config.

```bash
# Register in Paperless-ngx post_consume_script or webhook config
curl -X POST http://localhost:3000/api/webhook/document \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "url": "http://paperless.local:8000/api/documents/123/",
    "prompt": "Extract invoice number, total amount, and due date only."
  }'
```

--------------------------------

### Contribute to Paperless-AI

Source: https://github.com/clusterzx/paperless-ai/blob/main/README.md

Follow these Git commands to fork the repository, create a new feature branch, commit your changes, and push them for a pull request.

```bash
git checkout -b feature/YourFeature
# After changes:
git commit -m "Add YourFeature"
git push origin feature/YourFeature
```

--------------------------------

### Set Node.js Environment Variables (Windows)

Source: https://github.com/clusterzx/paperless-ai/blob/main/RAG-DEV-GUIDE.md

Configure environment variables for the Node.js application on Windows. Set the RAG service URL and enable the RAG service.

```cmd
set RAG_SERVICE_URL=http://localhost:8000
set RAG_SERVICE_ENABLED=true
```

```powershell
$env:RAG_SERVICE_URL="http://localhost:8000"
$env:RAG_SERVICE_ENABLED="true"
```

--------------------------------

### Initialize and Interact with Document Chat

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Use `curl` to initialize a chat session for a specific document and send messages. Responses are streamed via Server-Sent Events (SSE).

```bash
# Initialize chat
curl http://localhost:3000/chat/init/123 \
  -H "x-api-key: your-api-key"
# { "documentTitle": "Acme Corp Invoice March 2024", "initialized": true }
```

```bash
# Send a message — SSE streaming response
curl -X POST http://localhost:3000/chat/message \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{ "documentId": "123", "message": "What is the total amount due on this invoice?" }' \
  --no-buffer
# data: {"content":"The total amount due on this invoice is "}
# data: {"content":"$1,250.00, with a due date of "}
# data: {"content":"March 30, 2024."}
# data: [DONE]
```

--------------------------------

### Get Processing History

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Retrieve paginated and filterable processing history. Supports filtering by tag ID, correspondent name, and free-text search. Compatible with DataTables jQuery plugin.

```bash
curl "http://localhost:3000/api/history?draw=2&start=10&length=10&correspondent=Acme%20Corp" \
  -H "x-api-key: your-api-key"
```

--------------------------------

### Retrieve Document Preview

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Returns the raw text content, title, ID, and resolved tag names for a Paperless-ngx document. This is used to populate the manual review interface.

```bash
curl http://localhost:3000/manual/preview/123 \
  -H "x-api-key: your-api-key"
```

--------------------------------

### Implement Lightbox for Image Previews

Source: https://github.com/clusterzx/paperless-ai/blob/main/docs/index.html

Handles opening and closing a lightbox modal for image previews. Images are displayed in a larger view with captions. Supports closing via the Escape key.

```javascript
// Lightbox functionality
function openLightbox(card) {
  const lightbox = document.getElementById('lightbox');
  const lightboxImg = document.getElementById('lightbox-img');
  const img = card.querySelector('img');
  const caption = card.querySelector('.screenshot-overlay h3').textContent;
  lightboxImg.src = img.src;
  document.querySelector('.lightbox-caption').textContent = caption;
  lightbox.classList.add('active');
  document.body.style.overflow = 'hidden';
}

function closeLightbox() {
  const lightbox = document.getElementById('lightbox');
  lightbox.classList.remove('active');
  document.body.style.overflow = 'auto';
}

// Close lightbox with escape key
document.addEventListener('keydown', (e) => {
  if (e.key === 'Escape') {
    closeLightbox();
  }
});
```

--------------------------------

### Query Parameter Documentation

Source: https://github.com/clusterzx/paperless-ai/blob/main/jsdoc_standards.md

Document query parameters similarly to path parameters, including default values and enumerated options if applicable.

```javascript
 *     parameters:
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 10
 *         description: Maximum number of records to return
```

--------------------------------

### Get Processing History

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Retrieves a paginated and filterable list of document processing history. It is compatible with DataTables jQuery plugin and supports filtering by tag ID, correspondent name, and free-text search.

```APIDOC
## GET /api/history

### Description
Returns paginated, filterable processing history compatible with the DataTables jQuery plugin. Supports filtering by tag ID, correspondent name, and free-text search across title, correspondent, and tags.

### Method
GET

### Endpoint
/api/history

### Query Parameters
- **draw** (integer) - Required - DataTables draw counter.
- **start** (integer) - Required - DataTables start index.
- **length** (integer) - Required - DataTables length.
- **correspondent** (string) - Optional - Filter by correspondent name.
- **tagId** (integer) - Optional - Filter by tag ID.
- **search[value]** (string) - Optional - Free-text search across title, correspondent, and tags.

### Response
#### Success Response (200)
- **draw** (integer) - The draw counter from the request.
- **recordsTotal** (integer) - Total number of records available.
- **recordsFiltered** (integer) - Total number of records after filtering.
- **data** (array) - An array of processing history objects.
  - **document_id** (integer) - The ID of the document.
  - **title** (string) - The title of the document.
  - **created_at** (string) - The timestamp when the document was processed.
  - **tags** (array) - An array of tags associated with the document.
  - **correspondent** (string) - The correspondent associated with the document.
  - **link** (string) - A link to the document.

### Request Example
```bash
curl "http://localhost:3000/api/history?draw=2&start=10&length=10&correspondent=Acme%20Corp" \
  -H "x-api-key: your-api-key"
```

### Response Example
```json
{
  "draw": 2,
  "recordsTotal": 100,
  "recordsFiltered": 8,
  "data": [
    {
      "document_id": 123,
      "title": "Acme Corp Invoice March 2024",
      "created_at": "2024-03-15T10:20:00",
      "tags": [{ "id": 3, "name": "Invoice", "color": "#FF5733" }],
      "correspondent": "Acme Corp",
      "link": "http://paperless.local:8000/documents/123/"
    }
  ]
}
```
```

--------------------------------

### Custom Prompt Analysis via Playground

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Runs document text through the AI with a fully custom prompt, bypassing the configured system prompt. This endpoint is ideal for prompt engineering and experimentation.

```bash
curl -X POST http://localhost:3000/manual/playground \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "content": "Lease agreement between John Doe and Property LLC. Monthly rent: $950. Start date: 2024-06-01.",
    "prompt": "List: tenant name, landlord name, monthly rent, and start date as JSON.",
    "documentId": "123"
  }'
```

--------------------------------

### Set Node.js Environment Variables (Linux/macOS)

Source: https://github.com/clusterzx/paperless-ai/blob/main/RAG-DEV-GUIDE.md

Configure environment variables for the Node.js application on Linux or macOS. Set the RAG service URL and enable the RAG service.

```bash
export RAG_SERVICE_URL=http://localhost:8000
export RAG_SERVICE_ENABLED=true
```

--------------------------------

### Run Paperless-AI with a Direct Docker Command

Source: https://github.com/clusterzx/paperless-ai/wiki/2.-Installation

This command directly runs the paperless-ai Docker image, mapping ports and volumes for persistent data. It's an alternative to using a docker-compose file.

```bash
docker run -d --name paperless-ai --network bridge -v paperless-ai_data:/app/data -p 3000:3000 --restart unless-stopped clusterzx/paperless-ai
```

--------------------------------

### Referencing Schema Components

Source: https://github.com/clusterzx/paperless-ai/blob/main/jsdoc_standards.md

Use the '$ref' syntax to reference complex or reusable schemas defined in '#/components/schemas'. This promotes consistency and reduces redundancy.

```yaml
 *               schema:
 *                 $ref: '#/components/schemas/Error'
```

--------------------------------

### Summary and Description

Source: https://github.com/clusterzx/paperless-ai/blob/main/jsdoc_standards.md

Details on how to provide a concise summary and a detailed description for each endpoint.

```APIDOC
## 2.3 Summary and Description

- Every endpoint must have a clear, concise `summary` field (single line)
- A more detailed `description` field using the pipe symbol (`|`) for multi-line content
- The description should:
  - Explain the purpose of the endpoint in 2-3 sentences
  - Describe key functionality and behaviors
  - Note any important side effects or dependencies
  - Use proper grammar and complete sentences
  - For complex endpoints, include usage examples or explanations of how the endpoint works in the larger application context

Example:
```javascript
/**
 * @swagger
 * /api/example:
 *   get:
 *     summary: Brief description of what this endpoint does
 *     description: |
 *       Detailed explanation of the endpoint functionality.
 *       This should cover what the endpoint does, how it works,
 *       and any important behaviors users should know about.
 *       
 *       Use multiple paragraphs for complex explanations.
 */
```
```

--------------------------------

### Update Settings Configuration

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Update existing Paperless-AI configuration by POSTing specific fields to the /settings endpoint. Only provided fields are merged into the .env file, and the server restarts to apply changes.

```bash
# Update only the scan interval and Ollama model
curl -X POST http://localhost:3000/settings \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{ \
    "aiProvider": "ollama", \
    "ollamaUrl": "http://ollama.local:11434", \
    "ollamaModel": "llama3.2", \
    "scanInterval": "*/15 * * * *", \
    "activateTagging": true, \
    "activateCorrespondents": true, \
    "activateDocumentType": true, \
    "activateTitle": true, \
    "restrictToExistingTags": "yes", \
    "restrictToExistingCorrespondents": "no" \
  }'
# { "success": true, "message": "Configuration saved successfully.", "restart": true }
```

--------------------------------

### AI Service Factory Usage

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Instantiate an AI service based on the `AI_PROVIDER` environment variable. Use the service to analyze documents or generate free-form text.

```javascript
const AIServiceFactory = require('./services/aiServiceFactory');

// Returns one of: openaiService | ollamaService | customService | azureService
const aiService = AIServiceFactory.getService();

// Analyze a document
const analysis = await aiService.analyzeDocument(
  documentContent,      // string: up to 50,000 chars
  existingTagNames,     // string[]: e.g. ['Invoice', 'Finance']
  correspondentNames,   // string[]: e.g. ['Acme Corp']
  documentTypeNames,    // string[]: e.g. ['Invoice', 'Contract']
  documentId,           // number
  customPrompt,         // string | null — overrides system prompt
  { restrictToExistingTags: true, restrictToExistingCorrespondents: false }
);
// Returns:
// {
//   document: { title, correspondent, tags, document_type, document_date, language, custom_fields },
//   metrics:  { promptTokens, completionTokens, totalTokens }
// }

// Generate free-form text (used by RAG Q&A)
const text = await aiService.generateText('Summarize the key points of this lease agreement...');
```

--------------------------------

### Settings Update

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Applies updated configuration settings to the application. Only provided fields are merged into the existing `.env` file.

```APIDOC
## Settings Update

### `GET /settings` and `POST /settings`

Renders the settings page and applies updated configuration. All fields are optional; only supplied fields are merged into the existing `.env`. The server restarts after 5 seconds to apply changes.

```bash
# Update only the scan interval and Ollama model
curl -X POST http://localhost:3000/settings \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{ 
    "aiProvider": "ollama",
    "ollamaUrl": "http://ollama.local:11434",
    "ollamaModel": "llama3.2",
    "scanInterval": "*/15 * * * *",
    "activateTagging": true,
    "activateCorrespondents": true,
    "activateDocumentType": true,
    "activateTitle": true,
    "restrictToExistingTags": "yes",
    "restrictToExistingCorrespondents": "no"
  }'
# { "success": true, "message": "Configuration saved successfully.", "restart": true }
```
```

--------------------------------

### Manual Document Analysis for Testing

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Analyzes raw document text using the configured AI provider and returns structured JSON metadata without altering Paperless-ngx. This is useful for testing AI interpretation of specific content.

```bash
curl -X POST http://localhost:3000/manual/analyze \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "content": "INVOICE\nFrom: Acme Corp\nDate: 2024-03-15\nAmount Due: $1,250.00\nInvoice #INV-2024-0042",
    "id": "preview-001"
  }'
```

--------------------------------

### Documenting Response Content Schema

Source: https://github.com/clusterzx/paperless-ai/blob/main/jsdoc_standards.md

Document the schema for a successful JSON response (200 OK) by referencing a component schema. Ensure the description accurately reflects the context of the successful operation.

```yaml
 *     responses:
 *       200:
 *         description: Detailed description of successful response
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ResponseSchema'
```

--------------------------------

### Basic JSDoc Structure

Source: https://github.com/clusterzx/paperless-ai/blob/main/jsdoc_standards.md

All API routes must be documented with a JSDoc comment block using the @swagger tag, placed immediately before the route handler function.

```APIDOC
## Basic Structure and Format

Every route in the API must be documented with a JSDoc comment block using the `@swagger` tag following the OpenAPI 3.0.0 specification. The documentation should be placed immediately before the route handler function.

```javascript
/**
 * @swagger
 * /path/to/endpoint:
 *   method:
 *     // Documentation content
 */
router.method('/path/to/endpoint', async (req, res) => {
```
```

--------------------------------

### Playground Custom Prompt Analysis

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Runs document text through the AI with a fully custom prompt, bypassing the configured system prompt. Ideal for prompt engineering and experimentation.

```APIDOC
## POST /manual/playground

### Description
Runs document text through the AI with a fully custom prompt (bypasses the configured system prompt). Used for prompt engineering and experimentation.

### Method
POST

### Endpoint
/manual/playground

### Parameters
#### Request Body
- **content** (string) - Required - The raw text content of the document.
- **prompt** (string) - Required - The custom prompt to use for analysis.
- **documentId** (string) - Optional - The ID of the document for context.

### Request Example
```bash
curl -X POST http://localhost:3000/manual/playground \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d 
    {
      "content": "Lease agreement between John Doe and Property LLC. Monthly rent: $950. Start date: 2024-06-01.",
      "prompt": "List: tenant name, landlord name, monthly rent, and start date as JSON.",
      "documentId": "123"
    }
```

### Response
#### Success Response
- **result** (string) - The AI's response, typically in JSON format.
- **metrics** (object) - AI processing metrics.
  - **promptTokens** (integer) - Number of tokens used in the prompt.
  - **completionTokens** (integer) - Number of tokens generated in the completion.
  - **totalTokens** (integer) - Total tokens used.

#### Response Example
```json
{
  "result": "{ \"tenant\": \"John Doe\", \"landlord\": \"Property LLC\", \"monthly_rent\": \"$950\", \"start_date\": \"2024-06-01\" }",
  "metrics": { "promptTokens": 112, "completionTokens": 38, "totalTokens": 150 }
}
```
```

--------------------------------

### Implement Tab Switching Functionality

Source: https://github.com/clusterzx/paperless-ai/blob/main/docs/index.html

Manages tabbed content interfaces. Clicking a tab activates it and displays its corresponding content, while deactivating others. Assumes elements have `data-tab` attributes linking them.

```javascript
// Tab switching functionality
document.querySelectorAll('.terminal-tab').forEach(tab => {
  tab.addEventListener('click', () => {
    // Remove active class from all tabs and content
    document.querySelectorAll('.terminal-tab').forEach(t => t.classList.remove('active'));
    document.querySelectorAll('.tab-content').forEach(c => c.classList.remove('active'));
    // Add active class to clicked tab and corresponding content
    tab.classList.add('active');
    document.getElementById(`${tab.dataset.tab}-content`).classList.add('active');
  });
});
```

--------------------------------

### RAG Ask a Question

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Ask a natural-language question about the document archive. The RAG layer retrieves context, document text, and uses an AI model for a grounded answer.

```bash
curl -X POST http://localhost:3000/api/rag/ask \
  -H "Content-Type: application/json" \
  -d '{ "question": "What was my total electricity cost in Q1 2024?" }'
```

--------------------------------

### Webhook Document Processing

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Accepts a Paperless-ngx document URL via webhook and queues it for AI processing. An optional custom prompt can override the default system prompt.

```APIDOC
## POST /api/webhook/document

### Description
Accepts a Paperless-ngx document URL (e.g., from a post-save webhook) and queues the document for AI processing. An optional custom prompt overrides the default system prompt for this document only.

### Method
POST

### Endpoint
/api/webhook/document

### Parameters
#### Request Body
- **url** (string) - Required - The URL of the document in Paperless-ngx.
- **prompt** (string) - Optional - A custom prompt to override the default system prompt.

### Request Example
```bash
curl -X POST http://localhost:3000/api/webhook/document \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d 
    {
      "url": "http://paperless.local:8000/api/documents/123/",
      "prompt": "Extract invoice number, total amount, and due date only."
    }
```

### Response
#### Success Response (202 Accepted)
- **message** (string) - Confirmation message.
- **documentId** (integer) - The ID of the processed document.
- **queuePosition** (integer) - The position of the document in the processing queue.

#### Response Example
```json
{ "message": "Document accepted for processing", "documentId": 123, "queuePosition": 0 }
```
```

--------------------------------

### Retrieve Document Thumbnail

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Proxies and caches document thumbnail images from Paperless-ngx. Cached PNGs are stored in `public/images/`.

```bash
curl http://localhost:3000/thumb/123 \
  -H "x-api-key: your-api-key" \
  --output thumbnail.png
```

--------------------------------

### Implement Code Copy Functionality

Source: https://github.com/clusterzx/paperless-ai/blob/main/docs/index.html

Adds functionality to copy code snippets to the clipboard when a copy button is clicked. Provides visual feedback by changing the button text to 'Copied!' temporarily.

```javascript
// Copy functionality
document.querySelectorAll('.copy-button').forEach(button => {
  button.addEventListener('click', (e) => {
    e.stopPropagation();
    const code = button.nextElementSibling.textContent;
    navigator.clipboard.writeText(code);
    // Change button text temporarily
    const originalText = button.innerHTML;
    button.innerHTML = '<i class="fas fa-check"></i> Copied!';
    setTimeout(() => {
      button.innerHTML = originalText;
    }, 2000);
  });
});
```

--------------------------------

### Basic JSDoc Swagger Structure

Source: https://github.com/clusterzx/paperless-ai/blob/main/jsdoc_standards.md

All API routes must be documented with a JSDoc comment block using the @swagger tag, placed immediately before the route handler.

```javascript
/**
 * @swagger
 * /path/to/endpoint:
 *   method:
 *     // Documentation content
 */
router.method('/path/to/endpoint', async (req, res) => {
```

--------------------------------

### RAG Index Management

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Control the document vector index in the RAG sidecar service. Use `/index` to start/refresh, `/index/status` to poll progress, and `/index/check` for stale documents.

```bash
# Start background indexing
curl -X POST http://localhost:3000/api/rag/index \
  -H "Content-Type: application/json" \
  -d '{ "force": false }'
```

```bash
# Poll status
curl http://localhost:3000/api/rag/index/status
```

```bash
# Check for stale documents
curl http://localhost:3000/api/rag/index/check
```

--------------------------------

### Trigger Immediate Document Scan

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Initiates an out-of-schedule document scan. This fetches unprocessed documents, runs AI analysis, and updates metadata. It respects `limitFunctions` configuration.

```bash
curl -X POST http://localhost:3000/api/scan/now \
  -H "x-api-key: your-api-key"
```

--------------------------------

### Tags and Categorization

Source: https://github.com/clusterzx/paperless-ai/blob/main/jsdoc_standards.md

Guidelines for assigning tags to endpoints for categorization and organization.

```APIDOC
## 3. Tags and Categorization

### 3.1 Tag Requirements

- Each endpoint must be assigned to at least one tag, often multiple tags
- Tags must come from the predefined list of application tags defined in the `tags` section
- Multiple tags should be used when an endpoint serves multiple purposes
- Common tag combinations include:
  - `[Navigation, X]` for UI page routes
  - `[API, X]` for data API endpoints
  - `[System, Authentication]` for security-related endpoints

### 3.2 Defined Tags

The application uses the following tags for categorization:
- Authentication - User authentication and authorization endpoints
- Documents - Document management and processing endpoints
- History - Document processing history and tracking
- Navigation - General navigation endpoints for the web interface
- System - Configuration, health checks, and administrative functions
- Chat - Document chat functionality
- Setup - Application setup and configuration
- Metadata - Endpoints for managing document metadata
- API - General API endpoints (usually combined with other tags)
```

--------------------------------

### Regenerate API Key

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Generates a new API key and updates the environment. Requires JWT authentication, not API key authentication.

```bash
# Must be called with a valid JWT cookie
curl -X POST http://localhost:3000/api/key-regenerate \
  -H "Cookie: jwt=<your-jwt-token>"
```

--------------------------------

### RAG Service Status

Source: https://context7.com/clusterzx/paperless-ai/llms.txt

Check the availability of the RAG Python sidecar and the configured AI backend.

```bash
curl http://localhost:3000/api/rag/status
```