Crate paperless_api

Expand description

§paperless-api

A small async Rust client for interacting with the Paperless-ngx API.

This crate provides PaperlessClient for talking to a Paperless instance and convenience types for working with documents, tags, custom fields, correspondents, document types, and tasks.

§Features

Async API built on reqwest
Access documents and related metadata from Paperless
Local metadata caching
Upload documents
Query task status

§Getting started

Create a client with your Paperless base URL and API token:

use paperless_api::PaperlessClient;

async fn run() -> Result<(), Box<dyn std::error::Error>> {
    let client = PaperlessClient::new(
        "https://paperless.example.com",
        "your-api-token",
        None,
    )?;

    Ok(())
}

§Refreshing cached metadata

The client keeps some metadata cached locally, such as tags, custom fields, correspondents, and document types.

You can refresh the caches individually or all:

use paperless_api::{PaperlessClient, RefreshMetaData};

async fn run() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = PaperlessClient::new(
        "https://paperless.example.com",
        "your-api-token",
        None,
    )?;

    client
        .refresh([
            RefreshMetaData::Tags,
            RefreshMetaData::CustomFields,
            RefreshMetaData::Correspondents,
        ])
        .await?;

    client.refresh_all().await?;

    Ok(())
}

§Creating and updating metadata

You can create, update and delete metadata items such as tags, correspondents, document types, etc. See CreateDto and UpdateDto

use paperless_api::metadata::{MatchAlgorithm, tag::*};

async fn run() -> Result<(), Box<dyn std::error::Error>> {
    let client = paperless_api::PaperlessClient::new(
        "https://paperless.example.com",
        "your-api-token",
        None,
    )?;

    // Create a new tag
    let created = client.create(&CreateTag {
        name: "invoices".to_string(),
        color: "#ff0000".to_string(),
        ..Default::default()
    }).await?;

    // Update the tag
    client.update(created.id, &UpdateTag {
        name: Some("paid invoices".to_string()),
        match_pattern: Some("invoice".to_string()),
        matching_algorithm: Some(MatchAlgorithm::AnyWord),
        is_insensitive: Some(true),
        ..Default::default()
    }).await?;

    // Delete a tag
    client.delete(created.id).await?;

    Ok(())
}

§Additional headers

If your paperless instance requires additional headers to be accessed, you can provide them during client creation:

let mut headers = std::collections::HashMap::new();
headers.insert("X-Custom-Header".to_string(), "value".to_string());

let client = paperless_api::PaperlessClient::new(
    "https://paperless.example.com",
    "your-api-token",
    Some(&headers),
).expect("Error creating client");

Re-exports§

pub use client::PaperlessClient;
pub use client::RefreshMetaData;
pub use document::Document;
pub use document_query::DocumentQuery;
pub use group::Group;
pub use saved_view::CreateSavedView;
pub use saved_view::SavedView;
pub use share_link::ShareLink;
pub use task::Task;
pub use user::User;
pub use workflow::Workflow;

Modules§

client: The central client for interacting with Paperless.
document: Types for working with Paperless documents.
document_query: Query for documents using the DocumentQueryBuilder.
dto: DTO traits and helpers.
group: Types related to groups.
id: Paperless ID types.
metadata: Metadata associated with documents.
note: Types related to notes.
saved_view: Types related to saved views in the paperless UI.
share_link: Types related to share links.
task: Types related to tasks.
user: Types related to users.
util: Utility types.
workflow: Types related to paperless workflows.

Enums§

Error