Skill: thistine/paperless-api (version 0.1.0)

--- name: paperless-api description: Upload and categorize documents using the Paperless-ngx API. Use for automating document management tasks with your Paperless-ngx instance. --- # Paperless API Skill This skill provides tools for interacting with your Paperless-ngx instance, specifically for uploading and categorizing documents. ## Configuration To use this skill, you need to provide your Paperless-ngx host URL and an API key. - **Host URL:** Your Paperless-ngx instance URL (e.g., `http://192.168.1.17:30070`) - **API Key:** Your Paperless-ngx API key (e.g., [REDACTED_SECRET]) ## Usage ### Uploading and Categorizing Documents Use the `upload_document.py` script to upload a document and optionally assign tags or a document type. **Script:** `scripts/upload_document.py` **Arguments:** - `--file_path`: Path to the document file to upload (e.g., `/path/to/invoice.pdf`) - `--host`: Your Paperless-ngx host URL - `--api_key`: Your Paperless-ngx API key - `--title`: (Optional) Title for the document - `--tags`: (Optional) Comma-separated list of tags (e.g., `"invoice,paid"`) - `--document_type`: (Optional) Document type name (e.g., `"Invoice"`) **Example:** ```bash python scripts/upload_document.py \ --file_path /path/to/my_document.pdf \ --host http://192.168.1.17:30070 \ --api_key 71ca2b0f4af4eeaec40e54832ed878ef30d1e053 \ --title "My Important Document" \ --tags "important,work" \ --document_type "Contract" ``` ## API Endpoints For detailed API endpoint information, refer to `references/api_endpoints.md`. (This file will contain specific API routes once we have more information.)

path: references/api_endpoints.md
content: # Paperless-ngx API Endpoints

This file is a placeholder for detailed information about Paperless-ngx API endpoints.

Once the official API documentation is accessible, this file should be updated with:

- Authentication details (if different from token header)
- Document upload endpoint and expected data format (e.g., `/api/documents/`)
- Document categorization/tagging endpoints (e.g., for updating existing documents)
- Endpoints for listing existing tags/document types (useful for categorization)
- Examples of request/response bodies.

**Commonly expected endpoints:**

- `POST /api/documents/`: Upload a new document.
- `GET /api/documents/{id}/`: Retrieve document details.
- `PATCH /api/documents/{id}/`: Update document properties (including tags, document type).
- `GET /api/tags/`: List all available tags.
- `POST /api/tags/`: Create a new tag.
- `GET /api/document_types/`: List all available document types.
- `POST /api/document_types/`: Create a new document type.


path: scripts/upload_document.py
content: 
import argparse
import requests
import os

def upload_document(file_path, host, api_key, title=None, tags=None, document_type=None):
    """
    Uploads a document to Paperless-ngx and optionally assigns tags and a document type.
    """
    url = f"{host}/api/documents/"
    headers = {
        "Authorization": f"Token {api_key}"
    }

    files = {
        "document": (os.path.basename(file_path), open(file_path, "rb"), "application/octet-stream")
    }

    data = {}
    if title:
        data["title"] = title
    if tags:
        # Assuming tags should be sent as a list of strings
        # Paperless-ngx might expect tag IDs rather than names, this is a common variance.
        # This implementation assumes names and Paperless will create them if they don't exist
        # or associate by name if it does.
        data["tags"] = [tag.strip() for tag in tags.split(',')]
    if document_type:
        # Similar to tags, assuming document_type name. Paperless-ngx might expect document_type ID.
        # This will likely require looking up the document type ID first if the API doesn't support
        # setting by name directly during upload.
        data["document_type"] = document_type

    try:
        response = requests.post(url, headers=headers, files=files, data=data, verify=False) # verify=False for self-signed certs
        response.raise_for_status()  # Raise an HTTPError for bad responses (4xx or 5xx)
        print("Document uploaded successfully!")
        print(response.json())
        return response.json()
    except requests.exceptions.HTTPError as errh:
        print(f"Http Error: {errh}")
    except requests.exceptions.ConnectionError as errc:
        print(f"Error Connecting: {errc}")
    except requests.exceptions.Timeout as errt:
        print(f"Timeout Error: {errt}")
    except requests.exceptions.RequestException as err:
        print(f"Ooops: Something Else: {err}")
    finally:
        # Ensure the file is closed after the request is complete
        files['document'][1].close()

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Upload and categorize documents to Paperless-ngx.")
    parser.add_argument("--file_path", required=True, help="Path to the document file to upload.")
    parser.add_argument("--host", required=True, help="Your Paperless-ngx host URL (e.g., http://192.168.1.17:30070).")
    parser.add_argument("--api_key", required=True, help="Your Paperless-ngx API key.")
    parser.add_argument("--title", help="(Optional) Title for the document.")
    parser.add_argument("--tags", help="(Optional) Comma-separated list of tags (e.g., 'invoice,paid').")
    parser.add_argument("--document_type", help="(Optional) Document type name (e.g., 'Invoice').")

    args = parser.parse_args()

    upload_document(args.file_path, args.host, args.api_key, args.title, args.tags, args.document_type)


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)