# Paperarchive - Full Documentation > Paperarchive is an AI-powered document management platform for freelancers and families. Upload any document (PDF, image, or Office file) and it is automatically OCR-processed, categorized, and made searchable. Data is hosted in Germany, text recognition and AI run in the EU, and the service is designed for the GDPR. The app runs at https://app.paperarchive.io, the public REST API at https://api.paperarchive.io/v1. This file contains the complete help and API documentation in a single Markdown document. A shorter overview is available at https://paperarchive.io/llms.txt, and a machine-readable OpenAPI spec at https://paperarchive.io/docs/openapi.json. All pages are also available as HTML under https://paperarchive.io/docs/ (German: https://paperarchive.io/de/docs/). # Part 1: Help Documentation --- ## Getting Started URL: https://paperarchive.io/docs/getting-started Set up Paperarchive in 5 minutes. Create your account, upload your first document, and see how automatic categorization and OCR search work in practice. # Getting started with Paperarchive Paperarchive turns messy documents into an organized archive, so you always find what you need. If you can forward a file, you can use Paperarchive. ## What you need - A Paperarchive account. - At least one document (PDF, image, or Office document). - Optional: your email client if you want email uploads. ## Quick start (5 minutes) - Create your account (email or Google). - Upload your first document. - Check Documents to see the processed file and review any action hints. - (Optional) Create your first Space. ## Your first upload - Click Upload in the top right. - Drag and drop a file (PDF, image, or Office document), or click to choose. - Wait for processing to finish. You will see the document in the Documents overview. If you prefer email: go to [Settings > Spaces](https://paperarchive.io/docs/spaces-and-email) and use your upload email. ## Where to go next - Documents: your full library with action hints for items that need attention. - Spaces: separate personal and business. - Settings: pick your language and preferences. ## Good first wins - Confirm a sender or category once. Paperarchive will reuse it later. - Add a Space for work vs personal. ## If something looks wrong - Open the document and edit the sender, category, or tags. - Use Undo right after an action if needed. If you want help fast, head to [Contact Support](https://paperarchive.io/docs/contact-support) and drop your email. I will pick it up. --- ## Account & Login URL: https://paperarchive.io/docs/account-and-login Create your Paperarchive account, sign in with email or Google, reset your password, enable two-factor authentication, and manage your active sessions. # Account and login ## Create an account You can sign up with: - Email and password - Google sign-in If you use email, Paperarchive sends you a verification link. Open it to activate your account. Check spam or promotions if you do not see it within a few minutes. ## Log in Go to the login page and use the same method you signed up with. If you used Google, always use the Google button. ## Forgot your password Use "Forgot password" on the login screen. Paperarchive sends you a reset link. The link is single use. If it expires, request a new one. ## Log out Open your profile menu and choose Log out. ## Google sign-in note If you signed up with Google, your email is managed by Google and cannot be changed in the app. --- ## App Overview URL: https://paperarchive.io/docs/app-overview A guided tour of the Paperarchive interface. Learn where to find your inbox, documents, spaces, categories, tags, and settings, and how to navigate fast. # App overview and navigation Paperarchive is split into clear areas so you can move fast. ## Main areas - Documents: your full library with upload, bulk actions, and action hints for items that need attention or clarification. - Search: find documents by keyword or meaning. - Categories, Tags, Senders: clean organization tools. - Spaces: separate contexts (personal, business, shared). - Settings and Profile: preferences, security, data export. - Billing: plan, trial, and limits. - Support: quick access to help. ## What lives where - Trash exists for Documents, Categories, Tags, and Senders. - Profile is for security and data (email, 2FA, export). - Settings is for product behavior (language, notifications). ## Tips - Check action hints in Documents regularly to keep things clean. - Use Spaces when you want a clear separation of topics. - If you cannot find an item, use Search first. --- ## Upload & Documents URL: https://paperarchive.io/docs/upload-and-documents Upload PDFs, images, and Office files to Paperarchive. Supported formats, drag-and-drop and email upload methods, and the basics of managing your archive. # Upload and documents ## What a document is In Paperarchive, a document is the proof. The system extracts the key information behind it (invoice, policy, receipt) and organizes it for you. ## Supported formats - PDF - Images: JPG, JPEG, PNG, HEIC, TIFF, GIF, WebP, BMP - Office documents: Word (DOC, DOCX), Excel (XLS, XLSX), PowerPoint (PPT, PPTX), OpenDocument (ODT, ODS, ODP) - Max size: 50 MB per file Office documents are automatically converted to PDF for text extraction and viewing, iPhone photos (HEIC) to JPEG. The original file is kept unchanged. If a file is larger, compress it or split it before upload. ## Upload options - Upload button: top right on Documents. - Drag and drop: drop files into the page. - Email upload: forward emails with attachments (see ["Spaces and Email Upload"](https://paperarchive.io/docs/spaces-and-email)). - Cloud folder: watch a Google Drive or Dropbox folder (see ["Cloud imports"](https://paperarchive.io/docs/cloud-imports)). You can upload multiple files at once. ## What happens after upload - File is validated. - Text is extracted (OCR). - Paperarchive suggests sender, category, tags, date, and filename. - You confirm anything with low confidence. Most files are ready in seconds. Large files can take longer. ## Manage documents - Open a document to preview and edit. - Bulk actions: download, update, or move to trash. - Trash keeps items for 30 days before permanent deletion. - Merge a front and back side, or split a batch scan: see ["Merge and split"](https://paperarchive.io/docs/merge-and-split). ## Common fixes - Wrong sender: edit the sender field and save. - Wrong category or tags: update them in the document view. - Wrong filename: rename it to match your style. --- ## Merge & Split URL: https://paperarchive.io/docs/merge-and-split Merge the front and back of a letter into one document, or split a file that contains several documents. How both actions work in Paperarchive. # Merge and split documents Sometimes the file does not match the document: the front and back of a letter were uploaded as two files, or one scan holds several letters. You can fix both from the document detail view. ## Merge documents Open the document that should stay, for example the front side. In the … menu at the top right, choose Merge…. - Add the other documents. Without a search term, Paperarchive shows the latest uploads from the same space. With a search term, you find documents by title. - Put the pages in the right order: drag and drop on a computer, the arrow buttons on a phone. - Decide whether title, sender, category and date should be detected again (on by default). - Click Merge documents. ### What happens next - The document you started from stays, with its tags, connections and your edits. It now holds all pages as one PDF. - Paperarchive processes the document again automatically. The text is always read again so search finds every page. This usually takes about a minute. - If detection is turned off, title, sender, category and date stay as they are. Fields you changed yourself are never overwritten. - The other documents move to the trash, where you can restore them for 30 days. Their tags and connections are not carried over. - If the document you started from was converted (for example an office file or a HEIC photo), its original file stays referenced. ### Good to know - PDFs, JPG, PNG and HEIC images and office documents can be merged. WebP, TIFF, GIF and BMP images cannot. - Phone photos are added the right way up, even if they were taken sideways. - You can merge up to 10 documents at once. All of them must be in the same space. ## Split a document If a file contains several documents, for example after a batch scan, you can split it into separate documents. ### Automatic suggestion Paperarchive checks on upload whether a file contains several documents. If it does, the detail view shows a notice with a suggestion. You can accept it, adjust the pages, or dismiss it. ### Split it yourself In the … menu, choose Split…. - Paperarchive shows every page with a short text preview. - Between two pages, tap Split here where a new document should start. Don't split removes a split point again. - Click Split into … documents. Empty pages, such as the backs of a double-sided scan, stay with the document before them. You cannot split in front of an empty page. ### Delete pages If you do not need a part at all, such as an ad insert or a cover sheet, delete it with the trash icon. This works in the Split… dialog and in the automatic suggestion under Adjust pages. Paperarchive asks first. The pages are then left out, and Restore brings them back as long as you have not confirmed yet. At least one part has to stay. If only one part is left, Paperarchive saves the document without the deleted pages. ### What happens next - Each part becomes its own document. Paperarchive processes the new documents automatically and detects title, sender, category and date for each part. They show up in your library shortly. - The original moves to the trash, where you can restore it for 30 days. Tags and connections of the original are not carried over. - Every part keeps a reference to the document it was split from, and the split is recorded in the change history. In a GoBD space the original stays in the trash as long as one of its parts is archived. ### When splitting is not possible - Only PDF files can be split. - The document needs at least two pages with content. Otherwise the menu entry is greyed out, or the dialog tells you there is nothing to split. ## When an action is not available - The document is still processing: wait until processing has finished. - GoBD protection: documents that are archived in a GoBD space cannot be merged or split. Documents that are not archived yet can be, and every step is recorded in the change history (see ["GoBD compliance"](https://paperarchive.io/docs/gobd-compliance)). - Shared spaces: you need edit rights for every document involved. --- ## Action Hints URL: https://paperarchive.io/docs/action-hints Paperarchive flags documents that need a quick check. Learn how action hints surface contracts, deadlines, low-confidence results, and unclear sender details. # Action hints When Paperarchive processes a document, it may need your input on certain details. Action hints appear directly in the Documents overview so you can quickly filter and resolve them. ## What are action hints Action hints are visual indicators on documents that need attention. You can select them to filter the documents list, making it easy to focus on what needs action. - Needs attention: time sensitive items (due soon). - Needs your input: Paperarchive needs a quick confirmation on sender, category, or other details. ## Common actions - Confirm: accept Paperarchive's suggestion. - Edit: fix sender, amount, or category. - Mark paid: for invoices. - Archive: file away. ## Undo After most actions you will see a toast with Undo for a few seconds. Use it right away if you clicked the wrong action. --- ## Processing & AI URL: https://paperarchive.io/docs/processing-and-ai Inside the Paperarchive pipeline: OCR text extraction, AI categorization, tag suggestions, and structured data extraction run automatically on every upload. # Processing and AI Paperarchive automatically processes every document you upload using AI-powered analysis. ## How processing works - Validate file type and size. - OCR extracts text from PDFs and images. - Paperarchive extracts sender, category, tags, dates, and summary. - Similarity matching connects related documents. Low confidence results create action hints on the document so you can review and confirm. ## Duplicate detection Paperarchive automatically detects duplicate uploads using SHA-256 content hashing. When you upload a file, a hash is computed on your device and verified on the server. If the same content already exists in your library, the upload is skipped and you are notified. For near-duplicates (re-scans, reformatted versions), Paperarchive uses embedding similarity to flag documents that are very similar to existing ones. These are marked for your review so you can decide whether to keep them. Duplicate detection works across all upload methods: the app, the API, and email forwarding. For an upload into a GoBD space, only a document in that same space counts as a duplicate; a copy in another space does not. ## Processing language Pick the language that best matches your documents. This improves OCR and extraction. Display language is separate and only affects the app UI. ## What Paperarchive detects - Sender: the company or person the document is from. - Category: the type of document (invoice, contract, etc.). - Tags: relevant labels extracted from the content. - Date: the document date (not the upload date). - Filename: a clean, descriptive name based on the content and your [naming preferences](https://paperarchive.io/docs/settings-and-profile). You can always edit any of these after processing. --- ## Search URL: https://paperarchive.io/docs/search Find any document in seconds using keyword search, full-text matching, semantic similarity, and filters by category, tag, sender, or date in Paperarchive. # Search Search is fast and smart. Use a few words and let Paperarchive do the rest. ## Search basics - Keyword search for exact terms. - Smart search for meaning and related content. - Results highlight matching text. Examples: - "telekom invoice" - "insurance 2024" - "electricity december" ## Filters and sorting Use filters to narrow by: - Date - Category - Tag - Sender - Space Tip: start broad, then narrow with filters. --- ## Categories URL: https://paperarchive.io/docs/categories Organize your archive with categories and nested subcategories. Paperarchive suggests categories automatically and lets you create custom ones per space. # Categories Categories are your main filing system. Use them for big buckets like "Utilities" or "Insurance". Paperarchive can suggest categories, and you can always override them. Use categories for stable structure, and tags for flexible labels. ## Create a category - Go to Categories. - Click New category. - Name it and save. You will see the document count next to each category. ## Duplicate hint Before a new category is created or renamed, Paperarchive checks your existing categories for the same or a similar name: other spellings ("&" or "and"), singular and plural ("Insurance" and "Insurances"), words that mean the same ("Car" and "Vehicle") and names that contain each other ("Electricity" and "Electricity bills"). If it finds one, you choose: - Use existing: the document goes into the category you already have. - Create as tag instead: useful when the name describes a topic across categories. - Create anyway: when you really want a separate category. ## Category suggestions Paperarchive does not create categories on its own. When a document fits none of your categories, it stays in "Uncategorized" and is marked as uncertain, and the category the AI would suggest lands in Category suggestions (the sparkle icon on the Categories page, with the number of open suggestions). The same suggestion for several documents is collected into one entry. - Create category: the category is created and the documents of the suggestion move there, unless you already sorted them yourself. - Assign to existing: the documents move to a category you pick, and later documents with the same suggestion follow. - Dismiss: the suggestion disappears and does not come back. Categories that came from a suggestion show a small sparkle icon. ## Subcategories (one level) You can add subcategories under a top level category. Nested levels deeper than one are not supported. This keeps navigation fast and clean. ## Edit and organize - Rename: change the label. - Move: move a category under another (when allowed). - Merge: combine multiple categories into one. Note: categories with children may have move restrictions. ## Merge and undo Select two or more categories, choose Merge and pick the category that stays. Paperarchive moves everything to it: the documents (also those in the trash), the subcategories, what it learned about which sender goes into which category, and your rules. A subcategory with the same name as one of the remaining category's is merged into that one. Renaming a category to the name of an existing one offers the same merge. The old name keeps working: new documents that would have gone into it land in the category that stays, and the old name does not come back as a category suggestion. Right after merging, the message at the bottom offers Undo. Later on, open Merges (the clock icon on the Categories page): it lists your merges, each with its own undo. Undo brings the merged categories back and puts everything where it was before. Whatever you changed yourself after the merge stays as it is, and Paperarchive tells you how many entries that concerns. - Paperarchive never merges on its own. Only you decide that. - Documents archived in a GoBD space keep their category, so a category with such documents can only be the one that stays. - "Uncategorized" cannot be merged into another category, but other categories can be merged into it. ## Trash and restore Deleted categories go to Trash for 30 days. You can restore or delete permanently. --- ## Tags URL: https://paperarchive.io/docs/tags Use tags as flexible cross-cutting labels for your documents. Combine them with categories to filter, search, and group records across any Paperarchive space. # Tags Tags are flexible labels that cut across categories, like "tax", "warranty", or "travel". They are great for topics that appear in many categories. ## Tags vs keywords - Keywords are terms Paperarchive extracts from a single document. - Tags are curated labels that appear in filters. Keywords are searchable, but only tags show up as filters. ## Manage tags - Create: add a tag manually. - Rename: update the label. - Merge: combine similar tags. - Trash: remove, with 30 day restore window. --- ## Senders URL: https://paperarchive.io/docs/senders How Paperarchive detects senders on invoices and letters, learns your renaming preferences, and groups documents by sender across every space. # Senders Senders are companies or people that send you documents. Paperarchive detects them automatically. You can also create a sender manually. ## When a sender needs review New or low confidence senders appear as "needs review". Use the Unconfirmed filter to review them fast. You can confirm a single sender or confirm all. Confirming a sender makes future documents easier to file. ## Manage senders - Rename: fix spelling or preferred name. - Merge: combine duplicates. - Trash: remove, with 30 day restore window. If a document shows the wrong sender, edit it from the document view. Tip: keeping senders clean improves future auto filing. ## Merge and undo Select the duplicates, choose Merge and pick the sender that stays. Paperarchive moves the documents, deadlines and events, your corrections, the learned filing rules and the email domains to it. Renaming a sender to the name of an existing one offers the same merge, and so do the possible duplicates Paperarchive points out at the top of the Senders page. The old name becomes a known name of the sender that stays, so the next document from it does not create the duplicate again. Right after merging you can click Undo in the message at the bottom. Later on, Merges (the clock icon on the Senders page) lists your merges, each with its own undo. Undo brings the merged sender back with its documents. Whatever you changed yourself after the merge stays as it is. Paperarchive never merges senders on its own. A sender with documents archived in a GoBD space can only be the one that stays. --- ## Spaces & Email Upload URL: https://paperarchive.io/docs/spaces-and-email Separate personal and business documents with spaces, and forward incoming receipts straight to Paperarchive via a unique email address per space. # Spaces and email upload Spaces let you separate areas like Personal, Business, or a specific project. Each space also has its own email address for uploads. ## What is a space Think of a space as a clean bucket for documents. You can switch spaces in the app or view all spaces at once. The default space is where uploads go if no space is specified. ## Create or edit a space - Go to Settings > Spaces. - Click Create space. - Pick a name, type, color, and emoji. You can set a default space and reorder spaces. If you delete a space, you choose where its documents should be moved. Space names can be changed later, and the email address updates with it. Each space can also have the GoBD mode enabled under the Advanced section in space settings. This adds automatic document archiving, retention periods, and deletion protection for all documents in that space. See the [GoBD compliance](https://paperarchive.io/docs/gobd-compliance) article for details. ## Name on documents Under "Name on documents" you enter how a space is addressed on invoices and letters, for example "Company B Ltd" with its address. Paperarchive reads the recipient of every document and files it into the matching space, no matter who sent it. This matters most when you run several companies and the same senders (phone provider, online shop, tax advisor) supply all of them. You do not have to set anything up first: when you move a document into one of your spaces, Paperarchive remembers its recipient and marks it as "learned" in that space, as long as most documents addressed to that recipient are filed there. From then on, documents addressed to that recipient land there directly. You can remove learned names at any time. Documents you upload into a specific space yourself (other than the default space), move there, send to a space email or route with a routing rule are never moved automatically. Only automatically assigned documents get corrected, for example those sent to the primary address or uploaded into the default space or from the All Spaces view. The recipient has to match exactly, including the legal form. Paperarchive never moves a document into a space you share with others (for example with your tax advisor) on its own. If a document belongs there, you see the space as a suggestion on the document and apply it with one click. That way an invoice never ends up with someone who should not see it by accident. ## Email upload You get: - One primary upload email (goes to your default space). - One unique email per space (goes directly there). Find them in Settings > Spaces and copy with one click. You can also download a vCard to save them in contacts. Use space emails when you want routing without extra clicks. ### Rules that matter - Only attachments are processed (PDF or images). - Max size is 50 MB per file. - The recipient address decides which space a document goes to, not the sender. You can forward from your company mailboxes too, for example from max@company1.com to the address of "Company 1". If "Only allowed senders" is on, max@company1.com has to be on your sender list. - New accounts start with "Only allowed senders" turned on and your signup address already on the list. Older accounts accept emails from any sender until you turn the list on. Under Settings > Spaces > Email security you can allow more addresses (billing@company1.com) or whole domains (@company1.com). The list applies to all your spaces. An empty list rejects everything. Emails from senders that are not on the list are not processed. If such an email had an attachment, you get a notice by email and in Paperarchive, at most once a day per sender. The sender is not told. - If an email fails the sender check of its domain (SPF, DKIM or DMARC), its documents get a Needs input item so you can review them. In a GoBD space such an email is never dropped: even an email without attachment is kept and marked for review. - Do not share your upload addresses. If you need a specific space, use its address. If not, use the primary one: with names on documents set up, Paperarchive files the documents itself. --- ## Cloud Imports URL: https://paperarchive.io/docs/cloud-imports Connect Google Drive or Dropbox, pick a folder to watch, and let Paperarchive import new documents from it automatically. # Cloud imports from Google Drive and Dropbox Connect Google Drive or Dropbox, pick one folder, and Paperarchive imports new files from it on its own. You can connect both services at the same time and watch one folder in each. ## Connect a service - Go to Settings > Integrations. - Click Connect Google Drive or Connect Dropbox. - Approve the read-only access on the provider's consent screen. - Search for the folder you want to watch and select it. Nothing is imported until you pick a folder. Until then the integration is connected but idle. ## What gets imported - Only files that sit directly in the folder you picked. Subfolders are ignored. - The same formats as a manual upload: PDF, images, and Office documents (see ["Upload and documents"](https://paperarchive.io/docs/upload-and-documents)). - Max 50 MB per file. - Large batches are imported in chunks of up to 25 files per sync run; the remainder follows automatically in the next runs. ## How often it syncs Paperarchive checks your watched folder about every 15 minutes, so a new file usually shows up within that window. If you do not want to wait, open Settings > Integrations and click Sync now. The same page shows the last sync time and the last error, if there was one. ## Where imported documents land Imported files go into your default space and run through exactly the same processing as a manual upload: text extraction (OCR), then suggestions for sender, category, tags, date, and filename. Anything with low confidence turns into an action hint, just like usual. ## Duplicates Paperarchive compares file content, not file names. If a file is already in your archive, it is skipped, even if it was renamed or copied. That also means switching the watched folder back and forth does not create duplicates. ## Access and privacy - Paperarchive asks for read-only access. It never changes, moves, or deletes anything in your cloud storage. - Your files stay where they are. Paperarchive imports a copy. - Access tokens are stored server-side and never reach your browser. - Disconnecting revokes the access token at the provider. ## Change the folder or disconnect You can pick a different folder at any time. The next sync then looks at the new folder from scratch. When you disconnect a service, documents that were already imported stay in Paperarchive, but no new files are imported. ## If nothing is imported - Check Last sync and the error line in Settings > Integrations. - The file type is not supported, or the file is larger than 50 MB. - The file sits in a subfolder of the watched folder. - The document is already in your archive. - More than 25 new files arrived at once. The remainder is imported automatically over the following runs (about every 15 minutes). - If the error mentions the connection or a token, disconnect and connect the service again. --- ## Shared Spaces URL: https://paperarchive.io/docs/shared-spaces Collaborate with family, partners, or your team in shared Paperarchive spaces. Invite members by email, manage roles and permissions, and keep an edit history. # Shared Spaces Shared Spaces let you collaborate with other people inside a single space. Invite family members, colleagues, or your accountant and control exactly what they can do. ## What is a shared space A shared space works like any other space, but with multiple users. Everyone who has access sees the same documents, categories, tags, and senders inside that space. Each member has a role that controls their permissions. The person who creates the space is the Owner. Owners can invite others and manage the space. Shared Spaces is a Premium feature. You need an active Premium plan or trial to create and manage shared spaces. ## Create a shared space - Go to Settings > Spaces. - Click Create space. - Pick a name, type, color, and emoji. Any space you create can be shared. After creation, open the space settings and go to Members to start inviting people. ## Invite members - Go to Settings > Spaces and select the space. - Click Members. - Click Invite Member. - Enter the email address, optionally a display name, and choose a role. - Click Send Invitation. The invited person receives an email with a link. If they already have a Paperarchive account, they can accept right away. If not, they can sign up first and then accept. You can cancel a pending invitation at any time from the Members page. ## Roles and permissions Every member of a shared space has a role. The table below shows what the four main roles can do; the auditor role for tax audits is described below the table. | Permission | Viewer | Editor | Admin | Owner | | --- | --- | --- | --- | --- | | View documents | ✓ | ✓ | ✓ | ✓ | | Search documents | ✓ | ✓ | ✓ | ✓ | | Upload documents | | ✓ | ✓ | ✓ | | Edit document details | | ✓ | ✓ | ✓ | | Move documents in/out | | ✓ | ✓ | ✓ | | Delete documents | | ✓ | ✓ | ✓ | | Invite new members | | | ✓ | ✓ | | Change member roles | | | ✓ | ✓ | | Remove members | | | ✓ | ✓ | | Cancel pending invitations | | | ✓ | ✓ | | Edit space settings | | | ✓ | ✓ | | Delete the space | | | | ✓ | | Transfer ownership | | | | ✓ | Owner - Full control. Every space has exactly one owner. Owners cannot leave their own space - they can transfer it to an admin first or delete it. Admin - Can manage members and settings, but cannot delete the space or transfer ownership. Editor - Can view and edit documents, upload new ones, and move documents in and out. Cannot manage members or settings. Viewer - Read-only access. Can view and search documents but cannot upload, edit, or move anything. Auditor - Read-only access for a limited time, for example for a tax audit. Can do what a viewer can, plus see the change history and create the GDPdU export. Access ends automatically on the date you choose; before that, only the owner or an admin can end it (an auditor cannot leave the space). See [Auditor access & tax exports](https://paperarchive.io/docs/auditor-access-and-tax-exports). ## Moving documents You can move documents between spaces you have access to. ### Moving documents into a shared space Select one or more documents, click Move, and choose the shared space as the target. You need at least Editor permissions in the target space. ### Moving documents out of a shared space Select documents in the shared space, click Move, and choose a personal space or another shared space where you have Editor or higher permissions. Documents that are GoBD-archived cannot be moved. Documents of a GoBD space that were never archived can be moved out; the move is recorded with the old and the new space. ### Who sees what after a move When you move a document into a shared space, all members can see it (according to their role). When you move a document out to your personal space, other members lose access. ## Leaving a shared space - Go to Settings > Spaces and select the shared space. - Click Members. - Click Leave at the bottom of the page. You will immediately lose access to all documents in that space. If you want to keep specific documents, move them to a personal space before leaving. Owners cannot leave their own space. To leave it, the owner transfers it to an admin first (see below); to remove it, the owner deletes it. ## Transfer a space The owner can hand a shared space to a member with the Admin role, for example before leaving a company or deleting their account. - Go to Settings > Spaces and select the shared space. - Click Members. - Click Transfer space next to the admin who should become the owner, and confirm. Afterwards that admin is the owner and you stay in the space as an admin. The space then runs on the new owner's plan, so they need an active Premium plan or trial. Only admins can receive a space (make the member an admin first), and your default space cannot be transferred. The transfer is recorded in the change history of the space. Afterwards you can leave the space or delete your account: the space, its documents and its history stay, also in a GoBD space with archived documents of other members. The iOS and Android apps offer the same action in the member list of the space. ## Free plan members and shared spaces Shared Spaces is a Premium feature. However, members who are on the Free plan can still be invited to and use a shared space owned by a Premium user: - The shared space runs on the owner's subscription. Document limits, AI features, and storage are counted against the owner's plan. - A Free plan user invited to a shared space can view, search, and (if they have the Editor role) edit documents in that shared space. - The Free plan member's own spaces and documents are still subject to their Free plan limits (100 documents, no AI, no smart search). - If the Free plan member only uses Paperarchive through shared spaces, they do not need to upgrade. ### What happens if the owner cancels their subscription - Uploads stop: No one can upload new documents to the shared space. - Documents stay: Existing documents remain accessible in read-only mode. - Editing stops: Members can no longer edit, move, or delete documents. - The space still exists: Once the owner reactivates their Premium plan, full access is restored automatically. ## Email upload in shared spaces Each space has its own upload email address. In a shared space, the upload email routes documents directly into the shared space, no matter which address sends them, as long as the address is on the owner's sender list (if "Only allowed senders" is on). The documents count toward the owner's account. Someone who only forwards invoices does not need to be a member. Only invite people who should see or edit the documents in Paperarchive. To control who may send documents by email, use the sender list under Settings > Spaces > Email security. ## Tips - Use shared spaces for household documents, small business paperwork, or projects with external partners. - Assign the Viewer role to people who only need to look up documents (like an accountant reviewing receipts). - Assign the Editor role to people who actively add and organize documents. - Use the Admin role sparingly - only for people who should also manage members. --- ## Settings & Profile URL: https://paperarchive.io/docs/settings-and-profile Configure processing preferences, interface language, two-factor authentication, account security, and full data export from your Paperarchive profile. # Settings and profile ## Settings Go to Settings to control how Paperarchive works. You can change: - Processing language (OCR and extraction) - Document naming template - Display language (English or German) - Timezone - Email notifications (processing updates and product updates) Changes apply to future documents, not ones already processed. ### Document naming Choose how the AI names your documents. Pick a template or build your own: - Compact: document type with date (e.g. "Invoice Feb 2026"). - Detailed: adds reference numbers (e.g. "Invoice RE-2026-0042 Feb 2026"). - With Sender: includes the sender name (e.g. "Cloudflare Invoice RE-2026-0042 Feb 2026"). - Custom: toggle sender, date, date format, and reference number individually. The default is Compact. Since the sender is a separate searchable field, it is not included in the name by default. A live preview shows exactly what names will look like. ### Smart dates in filenames Paperarchive adapts the date in the filename to how a document recurs, so dates only show up where they actually distinguish documents: - One-time documents (e.g. a purchase contract or a one-off receipt) get no date in the name. - Yearly documents (e.g. a tax assessment or annual statement) get only the year (e.g. "2026"). - Monthly documents (e.g. a payslip, utility bill, or bank statement) get month and year as before. The recurrence type is detected automatically. You can change it on any document - it updates the metadata (used for things like reminders for yearly documents) but does not rename the existing file, so your filenames stay stable. ## Profile Go to Profile for account and security. ### Change email If you did not sign up with Google, you can change your email. You will need to confirm the change via links sent to both addresses. If you used Google, the change is managed by Google. ### Two factor authentication (2FA) - Click Enable 2FA. - Scan the QR code with an authenticator app. - Enter the 6 digit code. - Optional: add a backup authenticator. If you lose access to both apps, you may lose access to your account. ### Data export Request an export from Profile > Data and Privacy. Paperarchive emails you when the export is ready; the email contains no link. You download the export in the app after signing in, through a link that is valid for 10 minutes. The files are deleted after 48 hours; after that you can request a new export. ### Delete account Start the deletion flow in Profile > Data and Privacy. Paperarchive emails you a confirmation link. This cannot be undone. If your own GoBD spaces hold archived documents that are still under retention, Paperarchive deletes them only after you confirm that you keep the records yourself; export them first. While a retention hold is active in one of your spaces, the deletion is refused until you release the hold or transfer the space. Archived documents you uploaded to a GoBD space of another owner stay there and pass to that owner, with their tags, sender and category; your IP address and browser are removed from their change history. See [GoBD mode](https://paperarchive.io/docs/gobd-compliance). --- ## Billing & Plans URL: https://paperarchive.io/docs/billing-and-plans Compare Paperarchive plans, start your free trial, upgrade on the web (also when you use the app), and manage your subscription and invoices. # Billing, trial, and plans Check your plan status in Billing. ## Plans at a glance - Trial: 30 days of full access. - Premium: unlimited documents and all Paperarchive features. - Free: up to 100 documents with basic organization. ## What happens after trial If payment succeeds, you keep full access. If payment fails, you enter a grace period with read only access. During grace period you can upgrade, or switch to Free and keep your 100 most recent documents. ## Free plan limit Free accounts can keep 100 documents. Once you reach the limit, new uploads pause, but your documents stay fully available. If you are over the limit (for example after your trial), extra documents are locked, not deleted. You can unlock everything by upgrading, or move documents you no longer need to the trash and empty it. Paperarchive emails you when you reach 80% and when you reach 100% of the limit, each time with the link to Billing. ## Upgrading and changing your plan You upgrade to Premium on the web at [app.paperarchive.io/billing](https://app.paperarchive.io/billing). You can also change or cancel your plan there at any time. Using the iPhone or Android app? The apps cannot sell plans and do not link to the purchase either, as Apple's and Google's rules require. They show your plan and usage under Settings > Billing. To upgrade, sign in with the same account in your browser. Once the upgrade is done, the app unlocks automatically, without an update and without signing in again. ## Manage subscription Use the Billing page on the web to open the customer portal and update payment details. You can also cancel or change your plan from there. --- ## AI Assistants (MCP) URL: https://paperarchive.io/docs/mcp-connector Connect Paperarchive to your AI assistant and chat with your documents: search your archive, ask about invoices and contracts, and get download links - straight from a conversation. Works with Claude, ChatGPT, and Grok. # Chat with your documents in your AI assistant Paperarchive connects to AI assistants as an MCP connector. Once linked, you can ask things like "Find my phone contract", "How much was the electricity bill in March?", or "List my latest bank statements" - and your assistant looks it up in your archive for you. The connector works with any assistant that supports custom MCP connectors, including Claude, ChatGPT, and Grok. ## What your assistant can do - Search your documents by content, sender, category, or tag. - Read document details like amounts, dates, and extracted text. - Look up transactions from processed bank statements. - Answer "What is open or due?" using the events Paperarchive extracts - invoices, contracts, and policies with state, amount, and due date. - Give you a short-lived download link for the original file. By default the connection is read-only. If you want, you can also let the assistant make a few changes for you (see "Letting the assistant make changes" below). It can never upload, delete, or reprocess documents. ## Letting the assistant make changes (optional) Some assistants ask for more than reading. On the approval page these permissions appear under Optional: allow changes, each with its own checkbox, and they are off until you tick them: - Resolve events: mark an invoice as paid, confirm an item that needs your input, archive it, or cancel it. Example: "Mark the electricity bill from March as paid." - Add & remove tags on documents: use your existing tags. Example: "Tag the last three receipts with Taxes 2026." The same rules as in the app apply: only in the Spaces you approved, only where you may edit (not in Spaces where you are a viewer or auditor), and the document's change log shows the change. Assistants usually ask you before they change something. AI assistants can make mistakes or be misled by text inside a document, so only allow changes if you keep an eye on what the assistant does. Removing a tag is remembered: Paperarchive will not add that tag to the document again automatically. ## What you need - A Paperarchive Premium plan (or an active trial) - the same requirement as for API keys. - An assistant plan that supports custom connectors (all three assistants require a paid plan for this). ## How connecting works The flow is the same everywhere: add this URL as a custom connector in your assistant, and you will be sent to Paperarchive to approve the connection. ``` https://api.paperarchive.io/mcp ``` - Add the URL in your assistant (exact steps per assistant below). - You are redirected to Paperarchive. Log in if needed. - Review the permissions, choose which Spaces the assistant may access, optionally allow changes, read the note on where your data goes, and click Allow access. - Back in your assistant, enable the connector in a chat and start asking questions. You can also find the URL with a copy button in the app under [Settings](https://paperarchive.io/docs/settings-and-profile) > Connections & API. If Paperarchive is listed in your assistant's connector or app directory, you can add it from there instead. ### Claude Paperarchive is listed in the [Claude connector directory](https://claude.ai/directory/paperarchive): open the listing and connect from there. Alternatively, in Claude (claude.ai or the desktop app) open Settings > Connectors, click Add custom connector, and paste the URL. On Team/Enterprise plans an admin adds the connector in the organization settings. ### ChatGPT In ChatGPT on the web, enable Developer mode under Settings > Apps > Advanced settings (on some accounts the toggle is under Settings > Connectors > Advanced). Then add a new connector with the URL and complete the approval flow. ### Grok Open [grok.com/connectors](https://grok.com/connectors), click New Connector, choose Custom, and paste the URL. ## Choosing Spaces During approval you decide which Spaces the connection can see, for example only your business Space. Everything outside the selected Spaces stays invisible to the assistant - this is enforced on the server, not just in the interface. ## Privacy - A connected assistant only receives what its tools request: search results, document details, and statement data from the Spaces you approved. - Document content that an assistant reads becomes part of your conversation with that assistant and is processed under the provider's privacy and storage rules, possibly outside the EU. Treat conversations with the same care as the documents themselves. - Shared Spaces also contain documents of other members. Only allow them if everyone would agree. - If you process data of customers or clients, you need your own data processing agreement with the assistant's provider. - You stay in control: disconnecting stops all access immediately. ## Disconnecting Go to Settings > Connections & API in Paperarchive and click Disconnect next to the app. Apps that may make changes are marked Can make changes. The assistant immediately loses access. You can reconnect at any time, for example to change which permissions it has. ## Troubleshooting - The assistant asks to re-authenticate: the login expired after longer inactivity. Just run the connect flow again. - The assistant cannot find a document: check that the document's Space was selected when you connected, and that processing has finished. - Upgrade notice during connect: the connector needs an active Premium or trial plan. - The assistant says it is not allowed to change something: you did not allow that change, or you can only read in that Space. Reconnect and tick the permission if you want to allow it. Developers find the technical details (OAuth, tools, Claude Code setup) in the [API documentation](https://paperarchive.io/docs/api/mcp-connector). --- ## Learning & Feedback URL: https://paperarchive.io/docs/learning-and-feedback How Paperarchive learns from your edits. Sender renames, category corrections, and tag tweaks feed back into the model so future uploads get sharper over time. # Learning and feedback Paperarchive learns from your edits so it gets better over time. ## How learning works When you edit a document, Paperarchive records: - Sender changes - Category changes - Tag changes - Filename patterns Those patterns are reused for similar documents. The more consistent you are, the faster results improve. ## Give feedback In the document view you can: - Confirm Paperarchive's suggestions - Edit fields - Trigger reprocessing Every confirmation or correction helps future results. ## Learning page Open Settings > Learning to see: - Patterns learned - Accuracy rate - Recent learning activity Learning data is private to your account. --- ## Content Policy & Privacy URL: https://paperarchive.io/docs/content-policy-and-privacy Which content is allowed in Paperarchive and how your data is protected. Covers acceptable use, prohibited material, encryption, and hosting in Germany. # Content policy and privacy ## Content policy Documents with the following content are not allowed: - Adult content - Violent content - Racy content - Spoofed or manipulated content If a file violates the policy, the file is deleted during processing (if the document is protected in a GoBD space, the file is moved to quarantine instead). The document entry stays in your list, marked as skipped, and shows the reason until you delete it. No email is sent. ## Privacy basics - Your files are stored in private storage. - Only you can access your documents, unless you share a space: members of a shared space see its documents according to their role. - The owner of a space can give an auditor (for example a tax auditor) time-limited read-only access to that space. - Paperarchive does not give your data to other users beyond that. If an upload fails, double check file type and size. If you have questions about data handling, [contact support](https://paperarchive.io/docs/contact-support). --- ## GoBD mode URL: https://paperarchive.io/docs/gobd-compliance GoBD mode in Paperarchive: retention periods, locked archived documents and events, change history with hash chain, integrity checks and deletion after expiry. # GoBD mode GoBD (Grundsätze zur ordnungsmäßigen Führung und Aufbewahrung von Büchern, Aufzeichnungen und Unterlagen in elektronischer Form) is a German regulation for keeping business records in electronic form. Paperarchive supports GoBD-compliant archiving with the GoBD mode, which you switch on per space. In GoBD mode, Paperarchive archives documents after processing, applies retention periods, locks archived documents and their key event details, records every change in a change history and checks the integrity of archived files regularly. Whether your record keeping as a whole meets the GoBD also depends on your own processes; your tax advisor can help with the procedural documentation. ## Who needs GoBD GoBD applies to all taxpayers in Germany who keep digital records. If you run a business, are self-employed, or manage tax-relevant documents digitally, GoBD rules apply to you. The key requirements are: - Documents must be stored unaltered for the legally required retention period. - Changes must be traceable. - Documents must not be deleted before the retention period expires. - The integrity of stored files must be verifiable. ## How to enable GoBD mode for a space GoBD mode is a per-space setting. Documents follow the rules of the space they belong to. - Go to Settings > Spaces. - Click the space you want to configure. - Expand the Advanced section at the bottom of the modal. - Turn on "GoBD mode (archiving with retention periods)". - Click Save. GoBD mode can only be enabled on existing spaces, not during space creation. When you switch GoBD mode on, every document in the space gets a retention period. GoBD mode cannot be switched off again while documents of the space are under retention or a retention hold is active, so in practice it stays on. The app tells you this before you switch it on. Every change of the setting is recorded in the change history. A GoBD space can only be deleted when it holds no archived documents and no retention hold is active. Archived documents whose retention period has ended have to be moved to the trash first. Documents that were never archived move to the space you choose. ## What happens in GoBD mode ### Automatic archiving A document is archived only when its processing (OCR, AI analysis, categorization) has completed and the SHA-256 hash of its original file exists. Right before archiving, Paperarchive checks the stored original against that hash. If they do not match, the document is not archived and the owner of the space is notified. - A document without open questions is archived right after processing. - If Paperarchive still needs your input on the document (Needs input), it is archived after you have reviewed it, at the latest 10 days after the upload. - An hourly run archives every completed document of the space that is at least 6 hours old and not archived yet, for example after you resolved a Needs input item or moved a document into the GoBD space. - The owner or an admin can also archive a document from its menu. Warning: failed uploads and documents whose processing failed are not archived automatically. They need a decision: retry the processing, or archive the document explicitly with a written reason. A document that is still not processed after 10 days is not archived automatically either; the owner of the space gets a notice in the app every week until it is processed again or archived explicitly with a reason. Every archiving is recorded in the change history with its reason: after processing, by the hourly run, after a review was confirmed, at the 10-day limit with an open question, manually, by a DATEV export, or explicitly for an incomplete document. Archiving cannot be undone. Until a document is archived, users cannot change or delete its original file or the files derived from it; only Paperarchive's own processing (conversion, split, merge) can. You can still edit the document, move it to the trash, delete it, split it, merge it with other documents and move it to another space; every step is recorded in the change history with the person who did it. From the moment of archiving, the recognized details (such as amount, date, sender and type) are locked, so check open Needs input items soon. The owner or an admin of the space can correct the index data with a mandatory reason: the document date, the sender, the category, the reference number, the extracted details and the values of the event (amount, currency, due date, reference number, type, period and cash discount); a missing event can be added. In the web app the edit form offers the date, the sender, the category and the due date. The change history keeps the old value, the new value and the reason. The file and the files derived from it, the file hashes, the date the document was added, the archive date and reason, the retention date, the space and the uploader never change. The original file is what counts; book from the original. ### Retention periods When a document is archived, Paperarchive sets its retention period based on the type of its event (invoice, contract, letter and so on). The retention period starts at the end of the calendar year of the document date, not the upload date. For example, an invoice dated March 15, 2026 has a retention period that starts at the end of 2026 and expires on December 31, 2034 (8 years). The following retention periods apply: | Document type | Retention | Legal basis | | --- | --- | --- | | Invoices | 8 years | HGB 257, AO 147 | | Receipts | 8 years | HGB 257, AO 147 | | Bank statements | 8 years | HGB 257, AO 147 | | Credit notes | 8 years | HGB 257, AO 147 | | Contracts | 10 years | HGB 257, AO 147 | | Insurance policies | 10 years | HGB 257, AO 147 | | Letters and correspondence | 6 years | HGB 257, AO 147 | | Offers | 6 years | HGB 257, AO 147 | | Notices and official documents | 6 years | AO 147 | | Payslips | 6 years | AO 147 | Documents without an event, or with a type not listed above, get a retention period of 10 years. A retention period is never shortened. Documents that were archived earlier keep the retention period they received at the time. Before a document is archived, a provisional retention period applies (end of the upload year plus 10 years); when the document is archived, it is replaced once by the period of its type. For contracts and insurance policies the owner or an admin can set the end of the contract; the period then starts at the end of that year. An archived document can only be moved to the trash and deleted after its retention period has ended. Documents that are not archived yet can be deleted at any time, also while the provisional period runs. 60 days before the retention period of archived records ends, the owner of the space gets a notice in the app. ### Retention hold (suspension of expiry) Records can be needed after their retention period, for example for an announced tax audit, a pending tax assessment or a legal dispute (suspension of expiry, Ablaufhemmung under § 147 (3) AO). Paperarchive does not detect this on its own. Instead, the owner or an admin of a GoBD space can set a retention hold for the whole space (in the space settings) or for one document (on the document page), with a reason and an optional end date. - While a hold is active, no document it covers is finally deleted, also after its retention period has ended. You can still move such a document to the trash, but emptying the trash after 30 days skips it. - The values in the change history of the covered documents are kept. - The space cannot be deleted and GoBD mode cannot be switched off. - Setting and releasing a hold, each with its reason, are recorded in the change history of the space. An active hold also blocks the deletion of the space owner's account: the deletion is refused until the hold is released or the space is transferred. - Retention holds are set in the web app. The iOS and Android apps do not show them yet. ### File integrity A SHA-256 hash is computed for every uploaded file. This hash acts as a digital fingerprint: if the stored file were ever altered, the hash would no longer match. The hash is also used to prevent duplicate uploads. When the app computes a hash during upload, the server compares it with its own hash of the stored file. If they differ, processing stops and you upload the file again. For archived documents in GoBD spaces, Paperarchive recomputes the hash of the stored file once a month and compares it with the hash saved at upload. You can also run this check for a single document at any time: open the document, go to the History tab and click "Check integrity". Every result is recorded in the change history. File hashing is active for all documents regardless of the GoBD setting. ### Change history Every change to a document is recorded together with who made it and when, with the previous and the new value. This includes: - Adding the document - Title, file name and document date - Reference number and the extracted details - Sender and category - Tags added or removed - Space assignment, trash and restore - Archiving with its reason, and the retention period - Corrections after archiving, with their reason - Splitting and merging - The document's event: amount, currency, due date, reference number, type and status - Integrity checks For the space, the change history also records GoBD mode on and off, moves of documents with the old and the new space, retention holds, the transfer of the space to a new owner, auditor access, every file an auditor opens or downloads, GDPdU exports and DATEV exports. The history cannot be edited or deleted through the app or the API. Entries are linked in a hash chain: each entry contains a hash of the previous one, so a changed or removed entry becomes detectable (tamper-evident). Paperarchive verifies this chain during the monthly integrity check. The stored old and new values are removed only by fixed deletion rules: when a document is finally deleted after its retention period, when the retention period of the records has ended, and when an account is deleted. A retention hold keeps them. Every removal is itself recorded, and the monthly integrity check compares the removals with these rules. When a document that was never archived is deleted from a GoBD space, its values are kept until the end of the year it was added plus 10 years and stay in the change history of the GDPdU export; if the owner of the space deletes their own account, these values are removed. Values whose document no longer exists are erased after 10 years. You can see the history of a document in the History tab of the document page (on mobile, in the History section below the document). Every member who can open the document sees its history from the time it has been in its current space. Only the person who uploaded it also sees the history from before. The owner and the admins of a GoBD space can export the change history of the space for a period as CSV or JSON in the space settings, next to the GoBD mode switch. The export includes the hash chain values. The change history is recorded for all documents regardless of the GoBD setting. ## What is locked after archiving Once a document is archived in a GoBD space, the following can no longer be changed: - The document content (extracted text) - The title (original name) and the document date - The assigned sender and category, also the sender and category names stored with the document - The reference number and the extracted details (structured data) - The file hashes, the stored file itself and the references to its files - The archive date, who archived it, the reason, the retention period and, for records passed to the space owner, the time of the transfer - The space: an archived document cannot be moved out of a GoBD space The event of an archived document is locked as well: amount, currency, due date, reference number and type cannot be changed directly, and the event cannot be deleted. You can still change its status, for example mark an invoice as paid; status changes are recorded in the change history. Wrong index data is corrected only through the correction with a mandatory reason (owner or admin, see above). Tags and other non-core metadata stay editable. When you try to change a locked detail, Paperarchive shows a message that the document is archived in GoBD mode. ## Deletion rules ### Documents that cannot be deleted - An archived document whose retention period is still running cannot be moved to the trash or deleted. - An archived document without a retention date cannot be deleted. - A document covered by an active retention hold is not finally deleted, also after its retention period. These rules are enforced in the database and apply to the app, the API and the internal service access. The only path past them is deleting your account: after you explicitly confirm that you keep the records yourself, archived documents in your own GoBD spaces are deleted with your account. An active retention hold blocks this: the deletion is refused until the hold is released or the space is transferred. Archived documents you uploaded to a GoBD space of another owner are not deleted; they pass to the owner of that space with their tags, sender and category, and your IP address and browser are removed from their change history. ### Documents that can be deleted - A document that is not archived yet can be moved to the trash, deleted, split and merged, also while its provisional retention period runs. Every step is recorded in the change history. - Once its retention period has expired, an archived document can be moved to the trash, restored and deleted again. Its other archived details stay locked. The deletion is recorded in the change history. - Documents in spaces without GoBD mode can always be deleted. ### When you move a document between spaces Archived documents cannot be moved out of a GoBD space. Documents that were never archived can be moved out; their retention ends, the GoBD rules no longer apply to them, and the move is recorded with the old and the new space. If you move a document into a GoBD space, it gets the provisional retention period and follows the GoBD rules from then on. The hourly run archives it once its processing has completed; if it is not processed, the owner gets the weekly notice described above. ### Source emails When the attachments of an email land in a GoBD space, Paperarchive also keeps the original email (.eml) and links it to every document created from it. If another email later brings an attachment that already exists in the space, Paperarchive creates no new document; it links the new email to the existing document as a further source email. Source emails are protected like the document and are part of the GDPdU export and of your data export. If an email fails the sender check of its domain (SPF, DKIM or DMARC), a GoBD space does not drop it: Paperarchive keeps it and marks it with a Needs input item for your review. For an upload into a GoBD space, only a document in that same space counts as a duplicate; a copy in another space does not. ## Plan limits Archived documents in GoBD spaces stay readable, downloadable and exportable (including the DATEV export) even if your account is over its plan's document limit, for example after a downgrade. They still count towards the limit. ## Things to know - GoBD mode is per space, not per document. All documents in a GoBD space follow the same rules. - Archiving happens automatically after successful processing and cannot be undone. Failed or unprocessed documents need your decision. - Retention periods are 6, 8 or 10 years depending on the document type. A retention hold keeps records beyond that. - File hashing and the change history are always active for all documents. GoBD mode adds archiving, retention periods, locks, deletion protection and the monthly integrity check. - GoBD mode cannot be switched off while documents of the space are under retention or a retention hold is active. ## Tax audits For a tax audit you can give an auditor time-limited, read-only access to a space and create a GDPdU export with `index.xml`, the tables and the original files. For your tax advisor there is the DATEV export. See [Auditor access & tax exports](https://paperarchive.io/docs/auditor-access-and-tax-exports). ## Your process documentation The GoBD require a process documentation (Verfahrensdokumentation) that describes how you capture, keep and check your records. Paperarchive cannot write it for you, but two documents help: - The [system description of the GoBD mode](https://paperarchive.io/compliance-documentation) explains what Paperarchive does technically, including its limits (for example: no independent backup copy of the files yet, read access of members is not recorded). - The [process documentation template](https://paperarchive.io/verfahrensdokumentation-vorlage) (German) covers responsibilities, document types, capture, scanning, retention, access, auditor access and controls. Fill it in and have your tax advisor review it. --- ## Auditor access & tax exports URL: https://paperarchive.io/docs/auditor-access-and-tax-exports Give a tax auditor time-limited, read-only access to a space, create a GDPdU export with index.xml for a tax audit, and hand your tax advisor a DATEV export. # Auditor access and tax exports During a tax audit (Betriebsprüfung) the tax office can ask for access to your digital records. The GoBD describe three ways: reading access in your system (Z1), evaluations you run on the auditor's instructions (Z2), and handing over the data on a storage medium (Z3). Paperarchive supports all three with the auditor role, search and exports, and the GDPdU export. For your tax advisor there is the DATEV export. ## Auditor role (read only, limited time) An auditor can read a space for a period you choose, and nothing else. ### Invite an auditor - Go to Settings > Spaces and select the space. - Click Members, then Invite Member. - Enter the email address and choose the role "Auditor (read only, limited time)". - Pick the date in "Access until". Access ends automatically at the end of that day, at most one year ahead. - Click Send Invitation. Owners and admins of the space can invite auditors. The space owner needs an active plan or trial, as for every shared space. The invitation link is valid for 7 days. The auditor needs a Paperarchive account to accept it. ### What an auditor can do | Auditor can | Auditor cannot | | --- | --- | | View and download documents and their files | Upload documents | | Search the space and see events and details | Change, move, archive or delete anything | | See the change history of every document | Invite or manage members | | Create the GDPdU export of the space | Change space settings | ### Change or end the access - In the member list you see until when each auditor has access. Use "Change access" to extend or shorten it. - To end the access right away, remove the person from the space. Only the owner or an admin can do this; the auditor cannot leave the space or end the access themselves. Access lasts at most 366 days. - After the end date the auditor has no access anymore. The entry stays in the member list as "Access expired" until you remove it, so you can see who had access and when. - The auditor role cannot be changed into another role or the other way round. Remove the person and invite them again with the role you want. - Granting, changing and removing auditor access is recorded in the change log of the space. ### Files an auditor opens are recorded Every file an auditor opens or downloads, in the web app, in the iOS and Android apps, through the Paperarchive API or through an AI assistant (MCP), is recorded in the change log of the space before the file is handed out. Auditors cannot read files directly from the file storage, only through this recorded link, so they need the current version of the iOS or Android app. If the entry cannot be written, the file is not handed out. Exports an auditor creates are recorded as well. ## Evaluations on request (Z2) If the auditor asks you to run evaluations yourself, use search and filters in Paperarchive, download the originals they need, or export the change log of a GoBD space as CSV or JSON in the space settings (owner and admins). Paperarchive does not include its own audit software. ## GDPdU export (Z3) The GDPdU export creates a ZIP archive in the format of the German tax authorities. Audit software such as IDEA reads it directly. - Open the Export menu in the header of the document list, or the export menu of the space in Settings > Spaces. - Choose "GDPdU export (tax audit)". - Pick the period: last year, this year, the last 3 years or a custom period of at most 11 years. The document date counts; documents without a document date count by the date they were added. - Click Create export. The ZIP contains: - `index.xml` following the description standard of the tax authorities (Beschreibungsstandard) - `dokumente.csv`, `ereignisse.csv` and `aenderungsprotokoll.csv`: documents, their events and every change log entry of the space in the period, including the hash chain values (UTF-8, semicolon separated, decimal comma, dates as DD.MM.YYYY in German time) - `fehlende_dateien.csv`: every file of an exported document that could not be included, with the reason - The original files in the folder `belege/`, plus the PDF views of e-invoices and emails, the source emails (also further emails that brought the same attachment) and the source files of merged documents Large exports are split into several ZIP files; each of them contains `index.xml` and all tables. Documents in the trash are not included, except archived documents that were moved to the trash after their retention period (column Papierkorb). Every export is recorded in the change log of the space. Owners, admins and auditors of a space can create the export. You have to be signed in; if you use two-factor authentication, Paperarchive asks for your code first. API keys cannot create this export. ## DATEV export for your tax advisor "Export for your tax advisor (DATEV)" in the same Export menu creates a ZIP with a DATEV booking batch (Buchungsstapel), an overview of the receipts (`belege.csv`) and the original files of the invoices, receipts and credit notes of the space for a period of at most one year. Owners, admins and editors of the space can create it; viewers and auditors cannot, because the export archives the exported documents in a GoBD space. The DATEV export is a handover to bookkeeping, not an audit export. Every DATEV export is recorded in the change log of the space. From a GoBD space, the DATEV export archives every document it contains. Documents with an open Needs input item are not exported; `belege.csv` lists them with a note. If archiving fails, no export is created. ## Things to know - The auditor role, the GDPdU export and the change log work in every space, but locks, retention periods and the hash-chain checks only apply in spaces with [GoBD mode](https://paperarchive.io/docs/gobd-compliance). - Read access of members (viewing, searching, downloading) is not recorded in the change log. Files that auditors open or download are. - Paperarchive does not yet keep an independent backup copy of the files. Create a GDPdU export of your GoBD space regularly and keep it outside Paperarchive. - For your own process documentation there is a [template (German)](https://paperarchive.io/verfahrensdokumentation-vorlage), and the [system description](https://paperarchive.io/compliance-documentation) explains how the GoBD mode works. --- ## Contact Support URL: https://paperarchive.io/docs/contact-support How to reach Paperarchive support fast: in-app chat, email, response times by plan, and the quickest path to help with billing or technical questions. # Contact support Need help? Reach out from the app or email me directly. ## Fastest way - Open Support in the app sidebar. - Add your email address (name is optional). - Submit your question. That is it. I will get back to you by email. ## Help me help you Include: - What you tried - The exact error message - A screenshot (if possible) - The document name or ID (from the URL) # Part 2: API Reference --- ## Introduction URL: https://paperarchive.io/docs/api/introduction Overview of the Paperarchive REST API: base URL, versioning, rate limits, request and response format, and what you can build on top of your document archive. # Introduction The Paperarchive API is a REST API that lets you integrate document management into any workflow - upload, search, categorize, and retrieve documents programmatically. It is designed for automations, integrations, and building custom workflows on top of your document archive. Prefer chatting instead of coding? Paperarchive also ships an [MCP connector](https://paperarchive.io/docs/api/mcp-connector) that plugs your archive straight into AI assistants like Claude, ChatGPT, and Grok. ## Base URL All API requests are made to: ``` https://api.paperarchive.io/v1 ``` ## Versioning The API is versioned via the URL path. The current version is `v1`. When breaking changes are introduced, a new version will be released while the previous version remains available for a deprecation period. ## Request Format Most request bodies are JSON-encoded with the `Content-Type: application/json` header. The exception is `POST /v1/documents` which accepts `multipart/form-data` for file uploads. Query parameters are used for filtering and pagination on GET endpoints. ## Response Format Most responses return JSON with a consistent envelope: ``` { "success": true, "data": { ... }, "total": 42, "limit": 50, "offset": 0 } ``` The download endpoint `GET /v1/document/:id/download` responds with a `302` redirect to a short-lived signed download URL - make sure your HTTP client follows redirects (e.g. `curl -L`). On errors, the response includes an error message: ``` { "success": false, "error": "Description of what went wrong" } ``` ## Quick Start Make your first API call by listing your documents: ``` curl -H "Authorization: Bearer pa_live_YOUR_KEY" \ https://api.paperarchive.io/v1/documents ``` You'll need an API key - see the [Authentication](https://paperarchive.io/docs/api/authentication) page for how to create one. ## Integration Quick Starts Connect Paperarchive to your favorite automation tools and start building powerful document workflows in minutes. [🤖 OpenClaw + Paperarchive Let your AI assistant manage documents autonomously - upload, search, and organize files through natural conversation via WhatsApp, Telegram, or Slack. Get started ->](https://paperarchive.io/docs/api/openclaw-quickstart) [⚡ n8n + Paperarchive Build visual document automation workflows - process invoices from email, sync with accounting tools, and trigger AI analysis on autopilot. Get started ->](https://paperarchive.io/docs/api/n8n-quickstart) --- ## Authentication URL: https://paperarchive.io/docs/api/authentication Authenticate against the Paperarchive API with personal API keys passed as Bearer tokens. Manage your keys, rotate them, and scope access to specific spaces. # Authentication The Paperarchive API uses Bearer token authentication with API keys. Every request must include your API key in the `Authorization` header. ## Creating an API Key Create and manage API keys in the Paperarchive app at [Settings > API Keys](https://app.paperarchive.io/settings#api-keys). Each key can be scoped to specific permissions and spaces. ## Using Your API Key Include the key in the `Authorization` header as a Bearer token: ``` Authorization: Bearer pa_live_abc123def456... ``` ## Key Format API keys use the prefix `pa_live_` followed by a random string. The full key is only shown once at creation time - store it securely. ## Scopes Each API key is assigned scopes that control what it can access. Available scopes: | Scope | Description | | --- | --- | | `documents:read` | List and retrieve documents | | `documents:write` | Create and delete documents | | `search` | Search across documents | | `events:read` | List and retrieve events (open items, due dates) | | `spaces:read` | List and retrieve spaces | | `categories:read` | List categories | | `categories:write` | Create and delete categories | | `tags:read` | List tags | | `tags:write` | Create and delete tags | | `senders:read` | List senders | | `senders:write` | Create and delete senders | ## Space Restrictions API keys can optionally be restricted to specific spaces. When restricted, the key can only access documents, categories, tags, and senders within those spaces. ## Security Best Practices - Use the minimum scopes needed for your integration - Restrict keys to specific spaces when possible - Rotate keys periodically - Never expose keys in client-side code or public repositories - Revoke compromised keys immediately --- ## Documents URL: https://paperarchive.io/docs/api/documents Endpoints to list, retrieve, download, upload, and delete documents in Paperarchive. With pagination, filters, multipart upload, and per-endpoint rate limits. ### GET /v1/documents List documents with pagination and optional filters. Results are scoped to spaces accessible by your API key. Required scope: `documents:read` Query parameters: - `limit` (integer, optional, default: 50): Number of documents to return (1-100). - `offset` (integer, optional, default: 0): Number of documents to skip for pagination. - `sort_by` (string, optional, default: created_at, one of: created_at, updated_at, title, document_date): Field to sort by. - `sort_order` (string, optional, default: desc, one of: asc, desc): Sort direction. - `space_id` (uuid, optional): Filter by space ID. - `category_id` (uuid, optional): Filter by category ID. - `status` (string, optional, one of: pending, processing, completed, failed, skipped): Filter by document status. - `created_after` (string (ISO 8601), optional): Filter documents created after this timestamp (e.g. "2026-03-30T10:00:00Z"). Useful for incremental syncs. Response example: ```json { "success": true, "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Invoice #2026-001", "document_date": "2026-01-15", "category_id": "cat-uuid-here", "sender_id": "sender-uuid-here", "space_id": "space-uuid-here", "file_type": null, "file_size": null, "status": "completed", "event_type": "invoice", "amount": 1200.00, "currency": "EUR", "structured_data": { "line_items": [ { "description": "Consulting services", "quantity": 1, "unit_price": 1200, "total": 1200, "tax_rate": 19 } ], "tax_breakdown": { "net_amount": 1008.40, "tax_amount": 191.60, "tax_rate": 19, "gross_amount": 1200 }, "payment_method": "bank_transfer", "order_number": "ORD-2026-042", "delivery_date": null, "recurring": null }, "created_at": "2026-01-15T10:30:00Z", "updated_at": "2026-01-15T10:32:00Z" } ], "total": 142, "limit": 10, "offset": 0 } ``` Response fields: - `id` (uuid): Unique document identifier. - `title` (string): Document title (AI-generated or user-set). - `document_date` (date): Date of the document (extracted or manual). - `category_id` (uuid | null): Assigned category ID. - `sender_id` (uuid | null): Identified sender ID. - `space_id` (uuid): Space the document belongs to. - `file_type` (string | null): MIME type of the uploaded file. Currently always null - reserved for a future release. - `file_size` (integer | null): File size in bytes. Currently always null - reserved for a future release. - `status` (string): Processing status: pending, processing, completed, failed, or skipped. Skipped means the document was not processed (duplicate or content policy). - `event_type` (string | null): AI-classified document type: invoice, offer, credit_note, contract, policy, statement, notice, receipt, payslip, letter, or null if not yet processed. - `amount` (number | null): Extracted monetary amount (e.g. invoice total, salary). - `currency` (string | null): ISO currency code for the amount (e.g. EUR, USD). - `structured_data` (object | null): Type-specific extracted metadata. Fields vary by event_type - see Structured Data section below. - `created_at` (datetime): When the document was created. - `updated_at` (datetime): When the document was last updated. ### GET /v1/document/:id/download Download the original file for a document by ID. Responds with a 302 redirect to a short-lived signed download URL (valid for 60 seconds) with a Content-Disposition attachment filename. Make sure your HTTP client follows redirects (curl -L; fetch and requests follow them by default). Alias: /v1/documents/:id/download. Requires access to the document space. Required scope: `documents:read` Path parameters: - `id` (uuid, required): The document ID. Response example: ```json { "success": true, "data": { "note": "This endpoint responds with a 302 redirect to a short-lived signed download URL. Following the redirect returns the binary file, not JSON." } } ``` ### GET /v1/documents/:id Retrieve a single document by ID, including the full OCR text, extracted structured data, and tags. Only accessible if the document is in a space your API key can access. Required scope: `documents:read` Path parameters: - `id` (uuid, required): The document ID. Response example: ```json { "success": true, "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Invoice #2026-001", "document_date": "2026-01-15", "category_id": "cat-uuid-here", "sender_id": "sender-uuid-here", "space_id": "space-uuid-here", "file_type": null, "file_size": null, "status": "completed", "event_type": "invoice", "amount": 1200.00, "currency": "EUR", "structured_data": { "line_items": [ { "description": "Consulting services - January 2026", "quantity": 1, "unit_price": 1200, "total": 1200, "tax_rate": 19 } ], "tax_breakdown": { "net_amount": 1008.40, "tax_amount": 191.60, "tax_rate": 19, "gross_amount": 1200 }, "payment_method": "bank_transfer", "order_number": "ORD-2026-042", "delivery_date": null, "recurring": null }, "ocr_text": "Invoice #2026-001\nDate: January 15, 2026\nFrom: Acme Corp...", "ai_title": null, "ai_summary": null, "tags": ["invoice", "acme-corp"], "created_at": "2026-01-15T10:30:00Z", "updated_at": "2026-01-15T10:32:00Z" } } ``` Response fields: - `event_type` (string | null): AI-classified document type: invoice, offer, credit_note, contract, policy, statement, notice, receipt, payslip, or letter. - `amount` (number | null): Extracted monetary amount (e.g. invoice total, salary). - `currency` (string | null): ISO currency code for the amount (e.g. EUR, USD). - `structured_data` (object | null): Type-specific extracted metadata. Fields vary by event_type - see Structured Data section below. - `ocr_text` (string | null): Full OCR-extracted text from the document. - `ai_title` (string | null): AI-generated title. Currently always null - reserved for a future release; use title instead. - `ai_summary` (string | null): AI-generated summary. Currently always null - reserved for a future release; use ocr_text and structured_data instead. - `tags` (string[]): Array of tag names associated with the document. ### POST /v1/documents Upload a document file (PDF, image, Office document or e-invoice XML). The file is stored securely and automatically processed through the OCR / AI pipeline - text extraction, metadata analysis, categorization, and embeddings all happen automatically. Send as multipart/form-data. File content is validated server-side via magic-byte signatures. The resolved target space is always checked for write access. Rate-limited to 10 uploads per minute. You can optionally pass a metadata JSON string to pre-populate document properties. Metadata you provide takes precedence over AI-extracted values - the AI still runs to fill in any gaps. Required scope: `documents:write` Body parameters: - `file` (file, required): PDF, JPEG, PNG, TIFF, HEIC, Office document (DOCX, DOC, PPTX, PPT, XLSX, XLS, ODT, ODS, ODP) or e-invoice XML (XRechnung / ZUGFeRD XML, UBL or CII, sent as application/xml or text/xml). Max 50 MB. Content is validated by magic bytes - the Content-Type header must match the actual file content. XML is accepted only when it is an e-invoice; amounts, dates, sender and payment details are then taken from the invoice data, and a PDF view is generated while the XML stays the original. - `space_id` (uuid, optional): Target space. Falls back to your default space if omitted. API keys restricted to specific spaces can only upload to those spaces. - `metadata` (JSON string, optional): Optional JSON string with custom metadata to pre-populate on the document. Your values take precedence over AI extraction. Supported fields: event_type (invoice, receipt, contract, policy, notice, payslip, letter, statement, offer, credit_note), state_hint (open, paid, active, expired), amount ({ value: number, currency: string }), sender_name (string), document_date (YYYY-MM-DD or ISO 8601), due_date (YYYY-MM-DD), paid_at (YYYY-MM-DD - marks the document as paid and creates a confirmed payment record), reference_number (string), tags (string array, max 5), category (string - category name), title (string - document title override). When paid_at is provided, the event is created directly in the "paid" state with a confirmed payment record - no manual confirmation needed. This is useful when your system already knows the payment status. Response example: ```json { "success": true, "message": "Document uploaded and processing started.", "data": { "id": "new-doc-uuid-here", "name": "invoice.pdf", "processing_state": "pending", "space_id": "space-uuid-here", "created_at": "2026-03-07T14:20:00Z" } } ``` Response fields: - `id` (uuid): Unique document identifier. - `name` (string): Original filename. - `processing_state` (string): Processing status: pending, processing, completed, error, or skipped. Skipped means the document was not processed because it is a duplicate or was blocked by content policy. - `space_id` (uuid): Space the document was uploaded to. - `created_at` (datetime): When the document was created. ### DELETE /v1/documents/:id Soft-delete a document. The document is marked as deleted but can be recovered. Only works for documents in spaces accessible by your API key. Required scope: `documents:write` Path parameters: - `id` (uuid, required): The document ID to delete. Response example: ```json { "success": true } ``` ### POST /v1/documents/:id/reprocess Run OCR and AI analysis again over the stored original file of a document, for example after a poor first pass on an old scan. The document keeps its ID; AI-generated fields (text, title, category, extracted fields, embeddings) are rebuilt while tags, fields you edited by hand and the space assignment are kept. The document stays visible with its current data until the new results are written. A document that is already being processed is not queued twice: the response says alreadyProcessing. Requires editor access to the document space. Required scope: `documents:write` Path parameters: - `id` (uuid, required): The document ID to reprocess. Response example: ```json { "success": true, "message": "Documents queued for reprocessing", "data": { "requested": 1, "queued": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"], "skippedPending": [], "denied": [], "notFound": [], "failed": [], "queuedCount": 1, "skippedPendingCount": 0, "deniedCount": 0, "notFoundCount": 0, "failedCount": 0, "limit": 50 } } ``` ### POST /v1/documents/reprocess Reprocess several documents in one call. Same rules as the single-document endpoint: at most 50 IDs per request, documents already in the pipeline are skipped and listed under skippedPending, documents you cannot edit under denied. The documents join the normal processing queue one after another. Required scope: `documents:write` Body parameters: - `documentIds` (uuid[], required): Document IDs to reprocess (1 to 50). Response example: ```json { "success": true, "message": "Documents queued for reprocessing", "data": { "requested": 2, "queued": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"], "skippedPending": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"], "denied": [], "notFound": [], "failed": [], "queuedCount": 1, "skippedPendingCount": 1, "deniedCount": 0, "notFoundCount": 0, "failedCount": 0, "limit": 50 } } ``` --- ## Statements URL: https://paperarchive.io/docs/api/statements Retrieve extracted transactions, balances, IBAN, period, and bank metadata from processed bank statements. Polling-friendly with a since parameter for incremental syncs. ### GET /v1/statements List bank statement documents with extracted transaction data. Supports incremental polling via the "since" parameter. Only statements whose structured_data has been populated are returned. Required scope: `documents:read` Query parameters: - `since` (string (ISO 8601), optional): Filter by updated_at >= since. Useful for incremental syncs (e.g. "2026-03-30T10:00:00Z"). - `limit` (integer, optional, default: 100): Maximum number of statements to return (1-500). Response example: ```json { "success": true, "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Kontoauszug March 2026", "original_name": "Kontoauszug_20260331.pdf", "original_created_at": "2026-03-31", "updated_at": "2026-04-01T10:30:00Z", "created_at": "2026-04-01T10:25:00Z", "structured_data": { "opening_balance": 10412.24, "closing_balance": 15279.34, "opening_balance_date": "2026-02-28", "closing_balance_date": "2026-03-31", "account_iban": "DE27500105175410883100", "statement_period": { "start": "2026-03-01", "end": "2026-03-31" }, "auszugsnummer": "3", "bank_name": "ING", "currency": "EUR", "transaction_count": 45, "extracted_at": "2026-04-01T10:29:45Z", "transactions": [ { "date": "2026-03-02", "value_date": "2026-03-02", "amount": -1000.00, "currency": "EUR", "counterparty": "Julia Klein", "counterparty_iban": null, "reference": "Haushaltsgeld", "type": "debit", "transaction_type": "Dauerauftrag" } ] } } ], "count": 1 } ``` Response fields: - `id` (uuid): Document ID of the bank statement. - `name` (string): Document title. - `original_name` (string): Original uploaded filename. - `original_created_at` (date): Statement date (extracted). - `updated_at` (datetime): When the statement was last updated - useful for incremental polling. - `created_at` (datetime): When the document was uploaded. - `structured_data` (object): Extracted statement data. See the Structured Data section for the full field reference. ### GET /v1/statements/:id/transactions Retrieve the full extracted transactions and statement metadata (balances, IBAN, period, bank name) for a single bank statement document. Required scope: `documents:read` Path parameters: - `id` (uuid, required): The bank statement document ID. Response example: ```json { "success": true, "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Kontoauszug March 2026", "original_name": "Kontoauszug_20260331.pdf", "original_created_at": "2026-03-31", "updated_at": "2026-04-01T10:30:00Z", "structured_data": { "opening_balance": 10412.24, "closing_balance": 15279.34, "account_iban": "DE27500105175410883100", "statement_period": { "start": "2026-03-01", "end": "2026-03-31" }, "bank_name": "ING", "currency": "EUR", "transaction_count": 45, "transactions": [ { "date": "2026-03-27", "value_date": "2026-03-27", "amount": 13502.53, "currency": "EUR", "counterparty": "KIRCHHOFF Automotive Deutschland GmbH", "counterparty_iban": null, "reference": "Verdienstabrechnung 03.26", "type": "credit", "transaction_type": "Gehalt" } ] } } } ``` Response fields: - `id` (uuid): Statement document ID. - `name` (string): Document title. - `structured_data` (object): Full extracted statement data. See the Structured Data section for field details. --- ## Events URL: https://paperarchive.io/docs/api/events Query the events Paperarchive extracts from documents - invoices, contracts, policies, notices, and more - including state, amount, and due date. Ideal for questions like "What is open or due?". ### GET /v1/events List events extracted from documents. Each event carries a state (e.g. "open", "paid", "active"), an optional amount, and an optional due date, and links to its source document. Events are visible when their linked document is in an accessible space; events without a document are not returned. Required scope: `events:read` Query parameters: - `state` (string, optional): Filter by state: received, needs_input, open, paid, expired, cancelled, archived, active. - `event_type` (string, optional): Filter by type: invoice, offer, credit_note, statement, contract, policy, notice, receipt, payslip, letter. - `due_before` (date (YYYY-MM-DD), optional): Only events with a due date on or before this date. - `due_after` (date (YYYY-MM-DD), optional): Only events with a due date on or after this date. - `space_id` (uuid, optional): Only events whose document is in this space. - `document_id` (uuid, optional): Only events attached to this document. - `limit` (integer, optional, default: 25): Maximum number of events to return (1-100). - `offset` (integer, optional, default: 0): Pagination offset. Response example: ```json { "success": true, "data": [ { "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890", "event_type": "invoice", "state": "open", "state_changed_at": "2026-07-20T09:15:00Z", "needs_input_reason": null, "occurred_at": "2026-07-18T00:00:00Z", "due_date": "2026-08-15", "period_start": null, "period_end": null, "amount": 89.90, "amount_type": "payable", "currency": "EUR", "amount_confirmed": true, "skonto_percent": 2.00, "skonto_amount": 88.10, "skonto_due_date": "2026-07-28", "reference_number": "RE-2026-1042", "summary": "Electricity bill July 2026", "sender": { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "name": "Stadtwerke" }, "document": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Stadtwerke_Rechnung_Juli.pdf", "space_id": "c3d4e5f6-a7b8-9012-cdef-345678901234" }, "created_at": "2026-07-20T09:14:00Z", "updated_at": "2026-07-20T09:15:00Z" } ], "total": 1, "limit": 25, "offset": 0 } ``` Response fields: - `id` (uuid): Event ID. - `event_type` (string): Event type (invoice, contract, policy, ...). - `state` (string): Current state in the event lifecycle. - `due_date` (date): Payment or action deadline, if any. - `amount` (number): Monetary amount, if any. - `skonto_due_date` (date): Early-payment discount deadline, if extracted. - `sender` (object): Sender of the underlying document ({ id, name }), if detected. - `document` (object): Linked source document ({ id, title, space_id }). ### GET /v1/events/:id Retrieve a single event by ID, including amounts, deadlines, reference number, sender, and the linked source document. Required scope: `events:read` Path parameters: - `id` (uuid, required): The event ID. Response example: ```json { "success": true, "data": { "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890", "event_type": "invoice", "state": "open", "due_date": "2026-08-15", "amount": 89.90, "currency": "EUR", "reference_number": "RE-2026-1042", "summary": "Electricity bill July 2026", "sender": { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "name": "Stadtwerke" }, "document": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Stadtwerke_Rechnung_Juli.pdf", "space_id": "c3d4e5f6-a7b8-9012-cdef-345678901234" } } } ``` --- ## Structured Data URL: https://paperarchive.io/docs/api/structured-data Reference for the type-specific structured_data object returned on Paperarchive documents, including invoice, receipt, bank statement, and contract shapes. # Structured Data Every processed document includes an `event_type`, `amount`, `currency`, and a `structured_data` object with type-specific fields extracted by AI. The fields vary depending on the document's `event_type`. If the document has not been processed yet or the type could not be determined, all fields are `null`. ## invoice | Field | Type | Description | | --- | --- | --- | | `line_items` | `[{ description, quantity, unit_price, total, tax_rate }]` | Individual line items on the invoice. | | `tax_breakdown` | `{ net_amount, tax_amount, tax_rate, gross_amount }` | Tax calculation summary. | | `payment_method` | `string | null` | One of: bank_transfer, direct_debit, card, paypal. | | `order_number` | `string | null` | Referenced order or purchase number. | | `delivery_date` | `YYYY-MM-DD | null` | Delivery or service date. | | `recurring` | `{ is_recurring, frequency } | null` | Whether this is a recurring invoice (monthly, quarterly, yearly). | ## offer | Field | Type | Description | | --- | --- | --- | | `line_items` | `[{ description, quantity, unit_price, total }]` | Offered line items. | | `valid_until` | `YYYY-MM-DD | null` | Offer expiration date. | | `terms` | `string | null` | Brief summary of key terms. | ## credit_note | Field | Type | Description | | --- | --- | --- | | `original_invoice_ref` | `string | null` | Reference to the original invoice. | | `reason` | `string | null` | Reason for the credit note. | | `line_items` | `[{ description, quantity, unit_price, total }]` | Credited line items. | ## contract | Field | Type | Description | | --- | --- | --- | | `contract_type` | `string` | One of: rental, employment, service, insurance, subscription, other. | | `parties` | `[{ name, role }]` | Contract parties and their roles. | | `start_date` | `YYYY-MM-DD | null` | Contract start date. | | `end_date` | `YYYY-MM-DD | null` | Contract end date. | | `termination_notice` | `{ period_months, deadline } | null` | Notice period and deadline for termination. | | `auto_renewal` | `boolean | null` | Whether the contract auto-renews. | | `monthly_cost` | `{ value, currency } | null` | Monthly cost if applicable. | | `key_terms` | `[string]` | 1-3 key terms summarized as bullet points. | ## policy | Field | Type | Description | | --- | --- | --- | | `policy_type` | `string` | One of: health, liability, property, vehicle, life, legal, other. | | `insured_object` | `string | null` | What is insured. | | `coverage_amount` | `{ value, currency } | null` | Maximum coverage amount. | | `deductible` | `{ value, currency } | null` | Deductible amount. | | `premium_frequency` | `string | null` | Payment frequency: monthly, quarterly, semi-annual, annual. | | `cancellation_deadline` | `YYYY-MM-DD | null` | Deadline to cancel the policy. | ## notice | Field | Type | Description | | --- | --- | --- | | `notice_type` | `string` | One of: price_change, termination, renewal, rate_adjustment, information, warning, other. | | `effective_date` | `YYYY-MM-DD | null` | When the notice takes effect. | | `action_required` | `boolean` | Whether the recipient needs to act. | | `action_deadline` | `YYYY-MM-DD | null` | Deadline for required action. | | `previous_value` | `string | null` | Previous value (e.g. old price). | | `new_value` | `string | null` | New value (e.g. new price). | ## receipt | Field | Type | Description | | --- | --- | --- | | `payment_method` | `string | null` | One of: cash, card, bank_transfer, paypal, other. | | `items` | `[{ description, amount }]` | Purchased items. | | `location` | `string | null` | Store or purchase location. | | `tax_breakdown` | `{ net_amount, tax_amount, tax_rate } | null` | Tax calculation summary. | ## payslip | Field | Type | Description | | --- | --- | --- | | `employer` | `string | null` | Employer name. | | `pay_period` | `{ start, end } | null` | Pay period date range (YYYY-MM-DD). | | `gross_salary` | `{ value, currency } | null` | Gross salary amount. | | `net_salary` | `{ value, currency } | null` | Net salary amount. | | `deductions` | `[{ description, amount, type }]` | Deductions with type: tax, social_security, insurance, other. | | `bonuses` | `[{ description, amount }]` | Bonus payments. | | `hours_worked` | `number | null` | Hours worked in the period. | | `tax_class` | `string | null` | Tax class (German: Steuerklasse). | ## letter | Field | Type | Description | | --- | --- | --- | | `letter_type` | `string` | One of: information, request, complaint, confirmation, reminder, other. | | `response_required` | `boolean` | Whether a response is expected. | | `response_deadline` | `YYYY-MM-DD | null` | Deadline to respond. | ## statement Bank statements (`event_type = "statement"`) are processed by a dedicated extraction pipeline that parses transactions, balances, and statement metadata. The extracted data is returned as `structured_data`, and is also available via dedicated endpoints (see the [Statements](https://paperarchive.io/docs/api/statements) section). | Field | Type | Description | | --- | --- | --- | | `opening_balance` | `number | null` | Starting balance (Alter Saldo), signed. | | `closing_balance` | `number | null` | Ending balance (Neuer Saldo), signed. | | `opening_balance_date` | `YYYY-MM-DD | null` | Date of the opening balance. | | `closing_balance_date` | `YYYY-MM-DD | null` | Date of the closing balance. | | `account_iban` | `string | null` | IBAN of the account the statement belongs to. | | `statement_period` | `{ start, end } | null` | Statement period as ISO 8601 dates. | | `auszugsnummer` | `string | null` | Statement number if present. | | `bank_name` | `string | null` | Detected bank (e.g. ING, Sparkasse, Kontist). | | `currency` | `string` | Statement currency, defaults to EUR. | | `transactions` | `[{ date, value_date, amount, currency, counterparty, counterparty_iban, reference, type, transaction_type }]` | Extracted transactions. `type` is `debit` or `credit`; `transaction_type` is the raw bank label (Lastschrift, Dauerauftrag, Kartenzahlung, etc.). | | `transaction_count` | `number` | Number of extracted transactions. | | `extracted_at` | `datetime` | When the extraction ran. | --- ## Search URL: https://paperarchive.io/docs/api/search Full-text search across every document in spaces accessible to your API key. Results ranked by relevance, with support for keyword, phrase, and filter queries. ### POST /v1/search Search across all accessible documents using full-text search. Returns matching documents ranked by relevance. Required scope: `search` Body parameters: - `query` (string, required): Search query text. - `limit` (integer, optional, default: 20): Maximum results to return (1-50). - `space_id` (uuid, optional): Limit search to a specific space. Response example: ```json { "success": true, "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Invoice #2026-001 from Acme Corp", "document_date": "2026-01-15", "space_id": "space-uuid-here", "status": "completed", "rank": 0.95 } ], "total": 3 } ``` --- ## Spaces URL: https://paperarchive.io/docs/api/spaces Endpoints to list and retrieve the spaces your API key can access. Spaces organize Paperarchive documents into separate collections like Personal or Business. ### GET /v1/spaces List all spaces accessible by your API key. Spaces organize documents into separate collections (e.g. "Personal", "Business"). Required scope: `spaces:read` Response example: ```json { "success": true, "data": [ { "id": "space-uuid-1", "name": "Personal", "type": "personal", "color": "#3b82f6", "is_default": true, "created_at": "2025-06-01T08:00:00Z" }, { "id": "space-uuid-2", "name": "Business", "type": "custom", "color": "#10b981", "is_default": false, "created_at": "2025-07-15T12:00:00Z" } ] } ``` Response fields: - `id` (uuid): Unique space identifier. - `name` (string): Space display name. - `type` (string): Space type (personal, custom). - `color` (string): Hex color code for the space. - `is_default` (boolean): Whether this is the default space. - `created_at` (datetime): When the space was created. ### GET /v1/spaces/:id Retrieve a single space by ID. Required scope: `spaces:read` Path parameters: - `id` (uuid, required): The space ID. Response example: ```json { "success": true, "data": { "id": "space-uuid-1", "name": "Personal", "type": "personal", "color": "#3b82f6", "is_default": true, "created_at": "2025-06-01T08:00:00Z" } } ``` --- ## Categories URL: https://paperarchive.io/docs/api/categories Endpoints to list, create, and delete categories in Paperarchive. Categories are user-owned and assigned to spaces via the category_spaces model. ### GET /v1/categories List categories you own that are linked to any accessible space (legacy categories.space_id or rows in category_spaces). Each item includes membership_space_ids for all linked spaces. Required scope: `categories:read` Response example: ```json { "success": true, "data": [ { "id": "cat-uuid-1", "name": "Invoices", "color": "#ef4444", "icon": "receipt", "space_id": null, "membership_space_ids": ["space-uuid-1", "space-uuid-2"] }, { "id": "cat-uuid-2", "name": "Contracts", "color": "#8b5cf6", "icon": "document-text", "space_id": null, "membership_space_ids": ["space-uuid-1"] } ] } ``` Response fields: - `id` (uuid): Unique category identifier. - `name` (string): Category display name. - `color` (string): Hex color code. - `icon` (string): Icon name. - `space_id` (uuid | null): Legacy single-space column. Often null; prefer membership_space_ids. - `membership_space_ids` (uuid[]): Spaces this category is assigned to via category_spaces. ### POST /v1/categories Create a category and assign it to a space. If space_id is omitted, your default space is used (when it exists). Paperarchive checks the name against your existing categories first: when a top-level category with the same name (ignoring case and surrounding spaces) exists, it is returned with status 200 instead of creating a duplicate. When similar categories exist (other spelling such as "&" vs "and", singular/plural, synonyms like "Car"/"Vehicle", or names contained in each other), the request fails with 409 and error "similar_exists" plus the candidates; send force: true to create the category anyway. A new category returns 201. Required scope: `categories:write` Body parameters: - `name` (string, required): Category name. - `space_id` (uuid, optional): Target space for the first membership. Omit to use your default space. - `color` (string, optional): Hex color code (e.g. "#ef4444"). - `icon` (string, optional): Icon name. - `force` (boolean, optional): Create the category even when similar categories exist (skips the 409 similar_exists answer). An exact name still returns the existing category. Response example: ```json { "success": true, "data": { "id": "new-cat-uuid", "name": "Receipts", "color": "#f59e0b", "icon": null, "space_id": null, "origin": "api", "membership_space_ids": ["space-uuid-1"] } } // 409 when similar categories exist (retry with "force": true to create anyway) { "success": false, "error": "similar_exists", "candidates": [ { "id": "cat-uuid-7", "name": "Receipts & Invoices", "path": "Receipts & Invoices", "parent_id": null, "match_kind": "similar", "score": 0.7 } ] } ``` ### DELETE /v1/categories/:id Move a category you created to the trash (soft delete) when it is linked to at least one space your key can access (category_spaces or legacy space_id). Only the creator can delete a category; it can be restored in the app for 30 days, and its documents keep their assignment. Required scope: `categories:write` Path parameters: - `id` (uuid, required): The category ID to delete. Response example: ```json { "success": true } ``` ## Smoke test checklist (categories API) Use a test API key with `categories:read` and `categories:write` (and `spaces:read` so you can resolve space UUIDs). Run against staging or local API. - GET /v1/categories - Expect `200`, `success: true`, array `data`. Each item has `membership_space_ids` (array, possibly empty for legacy rows before backfill). - POST with explicit space_id - `POST /v1/categories` with body `{"name":"API Smoke Cat","space_id":""}`. Expect `201`, returned `membership_space_ids` contains that space. - POST without space_id - Same with only `{"name":"API Smoke Cat Default"}`. Expect `201` if a default space exists, or `400` with a clear error if not. - GET again - New category appears; `membership_space_ids` matches the space you used (or default). - POST the same name again - Expect `200` and the same `id` (no duplicate). - POST a similar name - e.g. the plural of the name. Expect `409` with `error: "similar_exists"` and `candidates`; with `"force": true` expect `201`. - DELETE - `DELETE /v1/categories/` with the new id. Expect `200` and `success: true`. Repeat GET to confirm it is gone (it is in the trash). - Restricted API key - With a key limited to one space, repeat POST targeting a space outside the key: expect `403`. --- ## Tags URL: https://paperarchive.io/docs/api/tags Endpoints to list, create, and delete tags. Tags are flexible cross-cutting labels that complement categories on every document in your Paperarchive archive. ### GET /v1/tags List all tags available in the spaces your API key can access: tags assigned to a space and tags used on documents in it. Each tag lists the spaces it is available in. Required scope: `tags:read` Query parameters: - `space_id` (uuid, optional): Only tags available in this space. Response example: ```json { "success": true, "data": [ { "id": "tag-uuid-1", "name": "urgent", "space_id": "space-uuid-1", "space_ids": ["space-uuid-1"] }, { "id": "tag-uuid-2", "name": "tax-2026", "space_id": null, "space_ids": ["space-uuid-1", "space-uuid-2"] } ] } ``` Response fields: - `id` (uuid): Unique tag identifier. - `name` (string): Tag name. - `space_id` (uuid | null): Kept for compatibility: one of space_ids (the tag's original space if listed, else the only listed space) or null. Use space_ids. - `space_ids` (uuid[]): Spaces (among those your key can access) in which this tag is available. ### POST /v1/tags Create a new tag in a space. Tag names are unique per user, ignoring case: if you already have a tag with this name, it is returned with status 200 instead of 201 and becomes available in the given space. Required scope: `tags:write` Body parameters: - `name` (string, required): Tag name. - `space_id` (uuid, required): Space to create the tag in. Response example: ```json { "success": true, "data": { "id": "new-tag-uuid", "name": "important", "space_id": "space-uuid-1" } } ``` ### DELETE /v1/tags/:id Delete a tag. Only works for tags in spaces accessible by your API key. Required scope: `tags:write` Path parameters: - `id` (uuid, required): The tag ID to delete. Response example: ```json { "success": true } ``` --- ## Senders URL: https://paperarchive.io/docs/api/senders Endpoints to list, create, and delete senders. A sender represents the company or person on incoming Paperarchive invoices, contracts, and letters. ### GET /v1/senders List all senders available in the spaces your API key can access: senders assigned to a space and senders of documents in it. Senders are automatically detected from documents by AI or can be manually assigned. Required scope: `senders:read` Query parameters: - `space_id` (uuid, optional): Only senders available in this space. Response example: ```json { "success": true, "data": [ { "id": "sender-uuid-1", "name": "Acme Corp", "space_id": "space-uuid-1", "space_ids": ["space-uuid-1"] }, { "id": "sender-uuid-2", "name": "Deutsche Telekom", "space_id": null, "space_ids": ["space-uuid-1", "space-uuid-2"] } ] } ``` Response fields: - `id` (uuid): Unique sender identifier. - `name` (string): Sender name. - `space_id` (uuid | null): Kept for compatibility: one of space_ids (the sender's original space if listed, else the only listed space) or null. Use space_ids. - `space_ids` (uuid[]): Spaces (among those your key can access) in which this sender is available. ### POST /v1/senders Create a new sender in a space. Sender names are unique per user, ignoring case: if you already have a sender with this name, it is returned with status 200 instead of 201 and becomes available in the given space. If you have a similar sender (other spelling or legal form, known alias, similar name, e.g. "ACME GmbH" for "Acme"), the request fails with status 409 and {"success": false, "error": "similar_exists", "candidates": [{"id", "name", "match_kind", "score"}]}. Use one of the candidates, or send the request again with "force": true to create the sender anyway. Required scope: `senders:write` Body parameters: - `name` (string, required): Sender name. - `space_id` (uuid, required): Space to create the sender in. - `force` (boolean, optional): Create the sender even if similar senders exist (skips the 409 similar_exists check). Default false. Response example: ```json { "success": true, "data": { "id": "new-sender-uuid", "name": "Acme Corp", "space_id": "space-uuid-1" } } ``` ### DELETE /v1/senders/:id Delete a sender. Only works for senders in spaces accessible by your API key. Required scope: `senders:write` Path parameters: - `id` (uuid, required): The sender ID to delete. Response example: ```json { "success": true } ``` --- ## OpenClaw Integration URL: https://paperarchive.io/docs/api/openclaw-quickstart Learn how to integrate Paperarchive with OpenClaw to build an AI-powered document assistant that uploads, searches, and organizes documents through natural language via WhatsApp, Telegram, Slack, and more. # OpenClaw + Paperarchive: Build an AI Document Assistant [OpenClaw](https://openclaws.io/) is an open-source AI assistant platform with 234,000+ GitHub stars that turns large language models into autonomous agents capable of taking real action - browsing the web, managing files, sending messages, and calling APIs. By connecting OpenClaw with the Paperarchive API, you can build a personal AI document assistant that manages your entire document archive through natural conversation on WhatsApp, Telegram, Slack, Discord, or any supported messaging channel. This guide walks you through a complete end-to-end setup: from installing OpenClaw and configuring Paperarchive API access, to building practical skills that let your AI assistant upload receipts from a photo, search for tax documents by asking a question, and automatically organize incoming files into the right categories. ## Why Combine OpenClaw with Paperarchive? Paperarchive already provides AI-powered document processing - automatic OCR, categorization, sender detection, and full-text search. OpenClaw adds a conversational interface layer on top, so instead of opening the Paperarchive app and navigating through menus, you simply message your assistant: - "Upload this invoice" - snap a photo on your phone and send it via WhatsApp. OpenClaw forwards it to Paperarchive, which handles OCR and categorization automatically. - "Find my electricity bill from January" - OpenClaw calls the Paperarchive search API and returns the matching document with a summary. - "How much did I spend on insurance this year?" - OpenClaw searches across all your documents, extracts amounts, and calculates a total. - "Create a new category called Medical" - OpenClaw calls the categories API and confirms the result. The combination turns document management from a chore into something that happens in the background while you go about your day. ## Prerequisites Before you start, you will need: - A Paperarchive account with an active subscription. [Sign up free](https://app.paperarchive.io/register) if you do not have one yet. - A Paperarchive API key with the scopes you want your assistant to use. Create one at [Settings > API Keys](https://app.paperarchive.io/settings#api-keys). For a full-featured assistant, enable all scopes: `documents:read`, `documents:write`, `search`, `spaces:read`, `categories:read`, `categories:write`, `tags:read`, `tags:write`, `senders:read`. - A machine to run OpenClaw - this can be your laptop, a home server, or a cloud VPS. OpenClaw supports macOS, Windows, and Linux. - An API key for an LLM provider - [Anthropic](https://www.anthropic.com/) (Claude), [OpenAI](https://openai.com/) (GPT), or a local model via [Ollama](https://ollama.com/). ## Step 1: Install OpenClaw OpenClaw runs on your own machine with your data staying private by default. Install it using one of these methods: ### Quick Install (macOS / Linux) ``` curl -fsSL https://get.openclaws.io | bash ``` ### Using Docker ``` docker run -d --name openclaw \ -p 3838:3838 \ -v openclaw-data:/data \ openclaws/openclaw:latest ``` ### From Source ``` git clone https://github.com/openclaw/openclaw.git cd openclaw npm install npm start ``` After installation, open the OpenClaw dashboard (usually at `http://localhost:3838`) and complete the initial setup by providing your LLM API key. ## Step 2: Configure the Paperarchive API Connection OpenClaw uses environment variables and configuration files to manage credentials securely. Add your Paperarchive API key to the OpenClaw configuration: ### Option A: Environment Variable ``` export PAPERARCHIVE_API_KEY="pa_live_your_key_here" export PAPERARCHIVE_BASE_URL="https://api.paperarchive.io/v1" ``` ### Option B: OpenClaw Config File In your OpenClaw configuration file (typically `~/.openclaw/config.json`), add: ``` { "secrets": { "paperarchive_api_key": "pa_live_your_key_here" }, "env": { "PAPERARCHIVE_BASE_URL": "https://api.paperarchive.io/v1" } } ``` Verify the connection by asking OpenClaw to make a test call: ``` curl -H "Authorization: Bearer pa_live_your_key_here" \ https://api.paperarchive.io/v1/documents?limit=1 ``` If you get a JSON response with `"success": true`, you are good to go. ## Step 3: Create the Paperarchive Skill OpenClaw extends its capabilities through skills - modular instructions and tool definitions that teach the assistant how to interact with external services. Create a Paperarchive skill that gives OpenClaw full access to your document archive. Create a file called `paperarchive.skill.md` in your OpenClaw skills directory: ``` # Paperarchive Document Management You have access to the Paperarchive API for document management. Use it when the user asks about documents, invoices, receipts, contracts, or files. ## API Base URL ${PAPERARCHIVE_BASE_URL} ## Authentication All requests require: Authorization: Bearer ${PAPERARCHIVE_API_KEY} ## Available Actions ### Search Documents POST /search Body: { "query": "search terms", "limit": 10 } Use this when the user asks to find, look up, or search for documents. ### List Documents GET /documents?limit=50&sort_by=created_at&sort_order=desc Use when the user wants to see recent documents or browse their archive. ### Upload Document POST /documents (multipart/form-data) Fields: file (required), space_id (optional) Use when the user sends a photo or file to be archived. ### Get Document Details GET /documents/:id Use to retrieve full details including OCR text and structured data. ### List Categories GET /categories Use when the user asks about available categories. ### Create Category POST /categories Body: { "name": "Category Name", "space_id": "uuid" } ### List Spaces GET /spaces Use when the user asks about their spaces or workspaces. ### Search and Summarize When the user asks a question about their documents (e.g. "how much did I spend on..."), search for relevant documents, read their OCR text, and provide a helpful summary. ## Response Guidelines - Always confirm successful uploads with the document title - When listing documents, format them in a readable list - When searching, highlight the most relevant results - If no results found, suggest alternative search terms ``` Place this file in your OpenClaw skills directory (typically `~/.openclaw/skills/`) and restart OpenClaw or reload skills from the dashboard. ## Step 4: Connect a Messaging Channel The real power of this integration is being able to manage documents from your phone. OpenClaw supports multiple messaging channels out of the box: ### WhatsApp Connect your WhatsApp number through the OpenClaw dashboard under Channels > WhatsApp. Once connected, you can send photos of receipts and documents directly to your assistant, and it will upload them to Paperarchive automatically. ### Telegram Create a Telegram bot via [@BotFather](https://t.me/BotFather) and add the bot token to OpenClaw. Telegram's file sharing capabilities make it ideal for sending PDFs and images. ### Slack / Discord For teams using Slack or Discord, connect your workspace to create a shared document assistant that the entire team can use. ## Step 5: Test the Integration Once everything is connected, try these commands with your assistant: ### Upload a Document Send a photo of a receipt or invoice to your assistant. OpenClaw will: - Receive the image from your messaging channel - Upload it to Paperarchive via `POST /v1/documents` - Paperarchive processes the image through OCR and AI analysis - Your assistant confirms the upload with the detected title and category ### Search Documents Try asking: "Find all invoices from Deutsche Telekom" ``` // OpenClaw makes this API call: POST https://api.paperarchive.io/v1/search { "query": "invoices Deutsche Telekom", "limit": 10 } ``` The assistant returns a list of matching documents with titles and dates. ### Ask Questions About Your Documents Try: "What was the total on my electricity bill from last month?" OpenClaw will search for the document, retrieve its OCR text, extract the relevant information, and provide a clear answer. ## Advanced Use Cases ### Automated Receipt Archival Set up a dedicated WhatsApp group or Telegram channel where you forward all receipts. OpenClaw watches the channel and uploads every image to Paperarchive automatically - no interaction needed. ### Scheduled Document Reports Use OpenClaw's cron functionality to generate a weekly summary of uploaded documents: ``` { "cron": { "weekly_document_report": { "schedule": "0 9 * * 1", "prompt": "List all documents uploaded in the last 7 days from Paperarchive and send me a summary on WhatsApp with the count per category." } } } ``` ### Smart Document Routing Teach OpenClaw to route documents to specific Paperarchive spaces based on content. For example, any document mentioning "tax" goes to the "Tax 2026" space, while invoices go to the "Business" space. ### Multi-User Setup for Families Run OpenClaw with multiple messaging connections so each family member can upload and search documents independently, all flowing into the same Paperarchive account with different spaces. ### Webhook-Triggered Processing Use OpenClaw's webhook endpoints to trigger document workflows from other systems: ``` curl -X POST http://localhost:3838/hooks/agent \ -H "Authorization: Bearer your-openclaw-token" \ -H "Content-Type: application/json" \ -d '{ "message": "Search Paperarchive for all unpaid invoices and send me a summary on Telegram", "agentId": "main" }' ``` ## Security Best Practices - Use minimum scopes: If your assistant only needs to search and read documents, create an API key with just `documents:read` and `search` scopes. - Restrict to specific spaces: Limit the API key to only the spaces your assistant should access. - Run OpenClaw locally: Keep sensitive document data on your own hardware rather than in the cloud. - Rotate API keys: Periodically generate a new Paperarchive API key and update your OpenClaw configuration. - Use OpenClaw's sandboxed mode: Enable sandboxing if you want to restrict OpenClaw's system access while still allowing API calls. ## Troubleshooting | Issue | Solution | | --- | --- | | OpenClaw does not call the Paperarchive API | Verify the skill file is loaded by checking the OpenClaw dashboard. Restart OpenClaw after adding the skill. | | "Invalid or missing API key" error | Check that the environment variable `PAPERARCHIVE_API_KEY` is set and starts with `pa_live_`. | | File upload fails | Ensure the file is under 50 MB. Paperarchive accepts PDF, JPEG, PNG, TIFF, HEIC, and Office documents (DOCX, XLSX, PPTX, ODT and more). | | Search returns no results | Confirm that documents exist in the spaces accessible by your API key. Try broader search terms. | | Messages not arriving from WhatsApp/Telegram | Check the messaging channel configuration in the OpenClaw dashboard and verify the bot token is correct. | ## Frequently Asked Questions ### Is OpenClaw free to use? Yes, OpenClaw is fully open-source and free. You only pay for the LLM provider you choose (Anthropic, OpenAI, or free with local models via Ollama) and your Paperarchive subscription. ### Can I use this integration with a local AI model? Absolutely. OpenClaw supports local models through Ollama, so the entire stack - OpenClaw, your LLM, and document processing - can run on your own hardware. Only the Paperarchive API calls go to the cloud. ### How does this differ from using the Paperarchive app directly? The app provides a full visual interface for managing documents. The OpenClaw integration adds a conversational layer - ideal for quick uploads from your phone, hands-free document lookups, and automated workflows that run without your input. ### Can multiple people use the same assistant? Yes. OpenClaw supports multi-channel setups, so you can connect WhatsApp for yourself and Telegram for a family member, all linked to the same Paperarchive account. Use separate spaces to keep documents organized per person. ### What happens to my data? OpenClaw runs on your machine and your documents are stored in Paperarchive (hosted in Germany, designed for the GDPR). No document data passes through OpenClaw's servers - the project is fully open-source and runs locally. ## Next Steps - Read the [Authentication guide](https://paperarchive.io/docs/api/authentication) for more on API key scopes and security - Explore the [Documents API](https://paperarchive.io/docs/api/documents) for all available endpoints - Try the [Search API](https://paperarchive.io/docs/api/search) to build powerful document queries - Check out the [n8n integration guide](https://paperarchive.io/docs/api/n8n-quickstart) if you want to build visual automation workflows - Visit the [OpenClaw GitHub repository](https://github.com/openclaw/openclaw) for the latest documentation and community skills --- ## n8n Integration URL: https://paperarchive.io/docs/api/n8n-quickstart Learn how to integrate Paperarchive with n8n to automate document workflows - process invoices from email, sync with accounting tools, back up documents, and build powerful no-code document processing pipelines. # n8n + Paperarchive: Automate Your Document Workflows [n8n](https://n8n.io/) is a powerful open-source workflow automation platform that connects hundreds of apps and services through a visual, node-based editor. By integrating n8n with the Paperarchive API, you can build automated document processing pipelines that run 24/7 without writing code - from email-to-archive workflows to accounting integrations and AI-powered document analysis. This guide walks you through the complete setup: installing n8n, configuring Paperarchive credentials, building your first automation workflow, and exploring advanced use cases for document management automation. ## Why Combine n8n with Paperarchive? Paperarchive provides AI-powered document storage with automatic OCR, categorization, and full-text search. n8n adds the automation layer that connects Paperarchive to the rest of your digital ecosystem: - Email-to-Archive: Automatically extract PDF attachments from incoming emails and upload them to Paperarchive for instant processing and categorization. - Accounting Sync: When Paperarchive categorizes a document as an invoice, forward the extracted data (amount, date, sender) to your accounting tool like Lexoffice, sevDesk, or QuickBooks. - Cloud Storage Backup: Watch a Google Drive or Dropbox folder for new files and automatically archive them in Paperarchive with AI-powered metadata extraction. - Notification Pipelines: Get a Slack or email notification when specific types of documents are uploaded, such as contracts nearing expiry or tax-relevant invoices. - Batch Processing: Upload hundreds of documents from a folder, CSV file, or API endpoint in a single automated run. ## Prerequisites Before you start, you will need: - A Paperarchive account with an active subscription. [Sign up free](https://app.paperarchive.io/register) if you do not have one yet. - A Paperarchive API key. Create one at [Settings > API Keys](https://app.paperarchive.io/settings#api-keys). For automation workflows, recommended scopes are: `documents:read`, `documents:write`, `search`, `spaces:read`, `categories:read`, `tags:read`, `senders:read`. - An n8n instance - either self-hosted or [n8n Cloud](https://n8n.io/cloud/). ## Step 1: Set Up n8n If you do not have n8n running yet, here are the quickest ways to get started: ### n8n Cloud (Fastest) Sign up at [n8n.io/cloud](https://n8n.io/cloud/) for a hosted instance with no setup required. A free trial is available. ### Docker (Self-Hosted) ``` docker run -d --name n8n \ -p 5678:5678 \ -v n8n-data:/home/node/.n8n \ n8nio/n8n ``` Open `http://localhost:5678` to access the n8n editor. ### npm (Self-Hosted) ``` npm install -g n8n n8n start ``` ## Step 2: Add Paperarchive Credentials in n8n In the n8n editor, you need to set up Paperarchive as a custom API credential so all your workflows can authenticate securely. - Open the n8n editor and go to Settings > Credentials - Click Add Credential and choose Header Auth - Configure the credential: Name: Paperarchive API - Header Name: Authorization - Header Value: Bearer pa_live_your_key_here - Click Save This credential will be available in all HTTP Request nodes throughout your workflows. ## Step 3: Build Your First Workflow - Email to Archive The most popular Paperarchive automation is the email-to-archive pipeline. Here is how to build it step by step: ### Workflow Overview This workflow watches your email inbox, detects messages with PDF attachments, uploads each attachment to Paperarchive, and sends you a confirmation notification. ### Node 1: Email Trigger Add an IMAP Email trigger node and configure it with your email credentials. Set it to check for new emails every few minutes. Enable Download Attachments to capture file data. ### Node 2: Filter Attachments Add an IF node to check if the email contains attachments. Set the condition to: `{{ $json.attachments.length > 0 }}` ### Node 3: Upload to Paperarchive Add an HTTP Request node with these settings: ``` Method: POST URL: https://api.paperarchive.io/v1/documents Authentication: Header Auth (select your Paperarchive API credential) Content-Type: multipart/form-data Body Parameters: - file: {{ $binary.attachment_0 }} - space_id: your-space-uuid (optional) ``` ### Node 4: Confirmation Add a Slack, Email, or Telegram node to send yourself a notification: ``` "New document archived: {{ $json.data.name }} - Processing started." ``` Activate the workflow and every email with a PDF attachment will now flow directly into your Paperarchive account. ## Step 4: Add Search and Retrieval Workflows Beyond uploading, n8n can automate document searches and data retrieval from Paperarchive. ### Webhook-Triggered Document Search Build a workflow that exposes a webhook endpoint for searching your document archive: ``` // Webhook node receives: POST https://your-n8n-instance.com/webhook/paperarchive-search { "query": "electricity bill January 2026" } // HTTP Request node calls: POST https://api.paperarchive.io/v1/search Headers: Authorization: Bearer pa_live_your_key Body: { "query": "electricity bill January 2026", "limit": 5 } // Response is returned to the webhook caller ``` This turns your Paperarchive into an API-accessible search service that any other tool or automation can query. ## Real-World Automation Recipes ### Recipe 1: Invoice Processing Pipeline Automatically process incoming invoices end-to-end: - Trigger: Email arrives with an invoice attachment - Upload: n8n sends the PDF to `POST /v1/documents` - Wait: Delay 30 seconds for Paperarchive to finish OCR and AI analysis - Retrieve: Fetch the processed document via `GET /v1/documents/:id` - Extract: Read the extracted amount, currency, and structured_data (line items, tax breakdown) directly from the response - Sync: Send the extracted data to your accounting tool (Lexoffice, sevDesk, Xero) - Notify: Post a summary to your Slack channel ``` // After document processing completes, the response includes: { "data": { "title": "Invoice #2026-0142", "event_type": "invoice", "amount": 29.99, "currency": "EUR", "structured_data": { "line_items": [ ... ], "tax_breakdown": { ... } }, "ocr_text": "Invoice #2026-0142\nDate: March 7, 2026\n...", "category_id": "invoices-category-uuid" } } ``` ### Recipe 2: Google Drive to Paperarchive Sync Automatically archive files dropped into a Google Drive folder: - Trigger: Google Drive trigger watches a "To Archive" folder - Download: Download the new file from Google Drive - Upload: Send the file to Paperarchive via the API - Move: Move the original file to an "Archived" folder in Google Drive - Log: Add a row to a Google Sheet with the document ID and timestamp This creates a seamless drop-and-forget workflow: put files in a folder on your phone or desktop, and they are automatically processed and archived. ### Recipe 3: Weekly Document Digest Get a weekly summary of all new documents in your archive: - Trigger: Cron node fires every Monday at 9 AM - Fetch: Call `GET /v1/documents?sort_by=created_at&sort_order=desc&limit=50` - Filter: Filter for documents created in the last 7 days - Group: Group documents by category - Format: Build a formatted HTML email with document counts per category - Send: Email the digest to yourself ### Recipe 4: Scan Folder Watcher If you use a network scanner (e.g. Brother, Fujitsu ScanSnap), set up a workflow that watches the scan output folder and uploads new files: - Trigger: Local File trigger watches `/scans/` folder - Upload: Send each new PDF to `POST /v1/documents` - Archive: Move the scanned file to a `/processed/` folder Combined with Paperarchive's automatic AI categorization, this creates a fully hands-free scanning-to-archive pipeline. ### Recipe 5: Document Expiry Alerts Monitor for contracts or documents that are about to expire: - Trigger: Daily cron at 8 AM - Search: Call `POST /v1/search` with query "contract" or "expires" - Retrieve: Get full document details and check `document_date` - Filter: Find documents expiring within the next 30 days - Alert: Send a notification via email, Slack, or push notification ## Working with the Paperarchive API in n8n ### HTTP Request Node Configuration All Paperarchive API calls use the HTTP Request node with these common settings: | Setting | Value | | --- | --- | | Base URL | `https://api.paperarchive.io/v1` | | Authentication | Header Auth (Paperarchive API credential) | | Content-Type (JSON) | `application/json` | | Content-Type (Upload) | `multipart/form-data` | ### Handling Pagination When listing documents, use pagination to process large archives: ``` // First request GET /v1/documents?limit=50&offset=0 // Use the 'total' field from the response to loop // Next request GET /v1/documents?limit=50&offset=50 // Continue until offset >= total ``` In n8n, use a Loop Over Items node or SplitInBatches node to process paginated results. ### Waiting for Document Processing After uploading a document, Paperarchive processes it asynchronously (OCR, AI analysis). If your workflow needs the processed data, add a Wait node (15-60 seconds depending on document complexity) before retrieving the document details: ``` 1. POST /v1/documents → Upload, get document ID 2. Wait 30 seconds → Allow processing to complete 3. GET /v1/documents/:id → Retrieve with OCR text and structured data ``` ### Error Handling Use n8n's built-in error handling to manage API failures gracefully: - Add an Error Trigger node to catch workflow failures and send alerts - Use IF nodes to check for `success: false` in API responses - Implement retry logic for `429 Too Many Requests` errors with a Wait node - Log errors to a Google Sheet or database for debugging ## Scaling Your Automation ### Rate Limiting The Paperarchive API allows 60 requests per minute per API key, and document uploads are limited to 10 per minute. When processing large batches: - Use n8n's SplitInBatches node to process 10 documents at a time - Add a Wait node (60+ seconds) between upload batches to stay under the 10 uploads/minute limit - Monitor the `RateLimit-Remaining` header in responses ### Multiple Workflows Create separate workflows for different automation tasks rather than one monolithic workflow. This makes debugging easier and allows you to activate/deactivate individual automations. ### Credential Management For production setups, create separate Paperarchive API keys for each workflow so you can revoke access to specific automations without affecting others. ## Security Considerations - Use minimum scopes: Create API keys with only the scopes each workflow needs. A read-only reporting workflow should not have `documents:write` access. - Restrict spaces: If a workflow only processes documents in a specific space, restrict the API key to that space. - Secure your n8n instance: Use HTTPS, strong passwords, and restrict network access to your n8n editor. - Rotate API keys: Periodically rotate Paperarchive API keys used in automated workflows. - Audit workflows: Regularly review active workflows to ensure they are still needed and functioning correctly. ## Troubleshooting | Issue | Solution | | --- | --- | | HTTP Request returns 401 | Verify your Header Auth credential has the correct API key with the `Bearer ` prefix (note the space). | | File upload fails with 400 | Ensure you are sending as `multipart/form-data` with the file in a field named `file`. Supported formats: PDF, JPEG, PNG, TIFF, HEIC, and Office documents (DOCX, XLSX, PPTX, ODT and more). | | Document has no OCR text after upload | Processing is asynchronous. Add a Wait node (30+ seconds) before retrieving the document details. | | Rate limit errors (429) | Add delays between requests using Wait nodes. Use SplitInBatches for bulk operations. | | Workflow does not trigger | Check that the workflow is activated (toggle in the top right). For email triggers, verify IMAP credentials and polling interval. | | Binary data issues | When downloading files from other services, use the `{{ $binary }}` expression to reference binary data in the HTTP Request body. | ## Frequently Asked Questions ### Is n8n free to use? n8n is open-source and free to self-host. n8n Cloud offers paid hosted plans with a free trial. Both options work with the Paperarchive API. ### Do I need coding skills to use n8n with Paperarchive? No. n8n's visual editor lets you build complete automation workflows by connecting nodes and configuring settings - no code required. For advanced use cases, you can add JavaScript expressions and code nodes. ### How many documents can I process automatically? There is no hard limit on the n8n side. Paperarchive's upload rate limit of 10 uploads per minute means you can archive roughly 600 documents per hour. For large batch imports, use pagination and delays to stay within limits. ### Can I trigger n8n workflows from Paperarchive? Yes. Create a webhook-triggered workflow in n8n and call that webhook URL from any system that supports outbound HTTP requests. This enables bi-directional integration. ### Which n8n version do I need? Any current version of n8n (1.x or later) supports HTTP Request nodes with Header Auth, which is all you need for the Paperarchive integration. No custom n8n nodes are required. ### Can I use this with n8n Cloud? Absolutely. The Paperarchive API is a public REST API accessible from any n8n instance, whether self-hosted or cloud-based. ## Next Steps - Read the [Authentication guide](https://paperarchive.io/docs/api/authentication) for more on API key scopes and restrictions - Explore the [Documents API](https://paperarchive.io/docs/api/documents) to see all available document operations - Try the [Search API](https://paperarchive.io/docs/api/search) for building search-powered automations - Check out the [OpenClaw integration guide](https://paperarchive.io/docs/api/openclaw-quickstart) for conversational document management - Browse [n8n's workflow templates](https://n8n.io/workflows/) for inspiration on building document automations - Visit the [API Playground](https://paperarchive.io/docs/api/playground) to test endpoints interactively --- ## MCP Connector URL: https://paperarchive.io/docs/api/mcp-connector Connect Paperarchive to AI assistants via the Model Context Protocol. Read access and optional changes, OAuth details, and setup guides for Claude, ChatGPT, and Grok. # MCP Connector Paperarchive ships a remote [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server. Once connected, an AI assistant such as Claude, ChatGPT, or Grok can search your archive, read document details, look up bank statement transactions, and hand you download links - directly from a conversation. If you allow it, the assistant can also mark invoices as paid, resolve other events, and add or remove tags. ## Endpoint ``` https://api.paperarchive.io/mcp ``` The server speaks MCP over Streamable HTTP and authenticates via OAuth 2.1. Any MCP client that supports remote servers with OAuth can connect. Authorization happens in the Paperarchive app: you log in, review the requested permissions, choose which Spaces the connection may access, and approve. By default the connection is read-only. Changes (resolving events, tagging documents) are separate permissions that stay off until the user ticks them on the consent page. Uploading, deleting, or reprocessing documents is never possible over MCP. ## Requirements - A Paperarchive account with an active Premium or trial plan (same requirement as API keys). - An MCP client that supports remote servers, for example Claude, ChatGPT, or Grok (see the setup guides below). ## Available tools | Tool | Scope | Description | | --- | --- | --- | | `search_documents` | `search` | Full-text search across titles, senders, categories, tags, and OCR text. | | `list_documents` | `documents:read` | Browse documents with filters (space, category, status, date) and pagination. | | `get_document` | `documents:read` | Document details incl. extracted fields, tags, and optionally OCR text. | | `get_document_download_link` | `documents:read` | Short-lived signed URL (10 minutes) for the original file. | | `list_statements` | `documents:read` | Bank statements with extracted structured data. | | `get_statement_transactions` | `documents:read` | Transactions, balances, IBAN, and period of a statement. | | `list_events` | `events:read` | Events (invoices, contracts, policies, ...) with state, amount, and due date - answers questions like "What is open or due?". | | `get_event` | `events:read` | Details of a single event incl. amounts, deadlines, reference number, and source document. | | `list_spaces` | `spaces:read` | Spaces the connection can access. | | `list_categories` | `categories:read` | Categories for filtering documents. | | `list_tags` | `tags:read` | Tags in the accessible Spaces. | | `list_senders` | `senders:read` | Detected senders in the accessible Spaces. | | `resolve_event` | `events:write` | Optional. Resolve one event: `paid`, `confirm`, `archive`, or `cancel` (same rules as in the app). | | `add_document_tags` | `document_tags:write` | Optional. Add existing tags (ids from `list_tags`) to a document. | | `remove_document_tags` | `document_tags:write` | Optional. Remove tags from a document; Paperarchive will not add them back automatically. | Only tools covered by the granted scopes appear in the client. All results are filtered to the Spaces selected during authorization. Every tool carries a title and explicit annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), so clients can ask for confirmation before a change; `resolve_event` and `remove_document_tags` are marked as destructive. ## How authorization works - OAuth 2.1 with PKCE (S256): clients identify themselves with a Client ID Metadata Document (an HTTPS URL as `client_id`) or register dynamically (RFC 7591); only public clients with PKCE are accepted. Discovery lives at `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource`. - Resource and issuer: tokens are bound to the resource `https://api.paperarchive.io/mcp` (RFC 8707), and every authorization response carries the `iss` parameter (RFC 9207). Loopback redirect URIs (for example Claude Code) match on any port. - Read scopes: `documents:read`, `search`, `events:read`, `spaces:read`, `categories:read`, `tags:read`, and `senders:read`. Without a `scope` parameter, these are requested. - Optional write scopes: `events:write` and `document_tags:write`. A client that requests them gets them only if the user ticks them on the consent page; the token response's `scope` names what was granted. A call to a tool outside the granted scopes answers `403` with `WWW-Authenticate: Bearer error="insufficient_scope"` and the needed scope. - Tokens: access tokens expire after 1 hour; refresh tokens rotate on every use and expire after 30 days of inactivity. Tokens are stored hashed. - Space restriction: the Spaces you select at approval time are a hard server-side filter for every tool call. - API keys as an alternative: clients without OAuth support can send a Paperarchive API key as a Bearer token in the `Authorization` header. The key's scopes and Space restrictions apply exactly as documented under [Authentication](https://paperarchive.io/docs/api/authentication). The optional write tools need OAuth; API keys only get the read tools over MCP. ## Changes through the assistant (optional) - Off by default: on the consent page every requested write permission is a separate checkbox that starts unticked. - Same rules as the app: changes run through the same database rules as the web and mobile apps. Only Spaces granted to the connection, only events and documents the user may edit (not as viewer or auditor), never on documents locked by the plan limit. - Traceable: the change log of the document names the user; Paperarchive also logs which connection made each change. - Limited: an action is only available where it fits the event's state (for example no "confirm" on a paid invoice), and each connection can make at most 30 changes per 10 minutes on top of the general rate limit. - Untrusted content: document text comes from uploaded or emailed files. The server instructions tell the assistant to change things only when the user asks in the conversation, never because a document says so. Clients such as Claude and ChatGPT use the annotations to ask before they run a tool that changes data. ## Managing and revoking access Connected apps are listed in the Paperarchive app under Settings > Connections & API. Apps that may make changes are marked Can make changes. Disconnecting an app immediately invalidates all of its tokens. To change the permissions of a connection, disconnect it and connect again. Access also ends automatically when your Premium plan lapses. ## Client setup The connection flow is the same everywhere: add `https://api.paperarchive.io/mcp` as a custom connector, get redirected to Paperarchive, log in, pick your Spaces, optionally allow changes, and click Allow access. Only the menu paths differ per client. If Paperarchive is listed in your assistant's connector or app directory, you can add it from there instead of entering the URL. ### Claude (claude.ai and Claude Desktop) - Open Settings > Connectors (Team/Enterprise: an admin does this under organization settings). Custom connectors require a paid plan (Pro, Max, Team, or Enterprise). - Click Add custom connector, enter the endpoint URL, and confirm. - Complete the Paperarchive approval flow, then enable the connector in a chat via the tools menu. ### Claude Code ``` claude mcp add --transport http paperarchive https://api.paperarchive.io/mcp ``` Claude Code opens the authorization flow in your browser on first use. Alternatively, authenticate with a Paperarchive API key instead of OAuth: ``` claude mcp add --transport http paperarchive https://api.paperarchive.io/mcp \ --header "Authorization: Bearer pa_live_YOUR_KEY" ``` ### ChatGPT - Available on paid plans (Plus, Pro, Business, Enterprise, Edu) in the web app. - Enable Developer mode: Settings > Apps > Advanced settings (the toggle has also lived under Settings > Connectors > Advanced - the location varies by rollout). - Add a new connector with the endpoint URL. ChatGPT supports Streamable HTTP with OAuth, so the standard approval flow runs. - Enable the connector in a conversation to use the Paperarchive tools. ### Grok - Open [grok.com/connectors](https://grok.com/connectors) and click New Connector. - Select Custom, enter the endpoint URL, and complete the Paperarchive approval flow. - Grok discovers the tools automatically and makes them available in conversations. ### Other MCP clients Any MCP client that supports remote Streamable HTTP servers works. With OAuth support, the standard approval flow runs; without it, use a Paperarchive API key in the `Authorization` header as described above. ## Troubleshooting - The client asks to re-authenticate: the refresh token expired or the connection was revoked. Re-run the connect flow. - Tools are missing: the corresponding scope was not granted. Disconnect and reconnect with the needed permissions. - 403 with `insufficient_scope`: the assistant tried a change you did not allow. Reconnect and tick the permission if you want it. - 403 or "Premium feature": the connector requires an active Premium or trial plan. - 429 responses: the connector shares the public API rate limit of 60 requests per minute per connection. --- ## Errors & Rate Limits URL: https://paperarchive.io/docs/api/errors Error response format, HTTP status codes, validation messages, and rate-limit headers returned by the Paperarchive API across every endpoint in this reference. # Errors & Rate Limits ## Error Format All error responses follow a consistent format: ``` { "success": false, "error": "Description of the error" } ``` ## HTTP Status Codes | Code | Meaning | | --- | --- | | `200` | Success - request completed. | | `201` | Created - resource was created successfully. | | `202` | Accepted - file uploaded, document record will appear shortly. | | `400` | Bad Request - missing or invalid parameters, unsupported file type, or Content-Type mismatch. | | `401` | Unauthorized - missing or invalid API key. | | `403` | Forbidden - API key lacks required scope or space access. | | `404` | Not Found - resource does not exist or is not accessible. | | `413` | Payload Too Large - uploaded file exceeds the 50 MB limit. | | `429` | Too Many Requests - rate limit exceeded (60 requests per minute per API key; document uploads are limited to 10 per minute). | | `500` | Internal Server Error - something went wrong on the server. | Note on duplicates: uploading a file that already exists in your library is not rejected with an error. The upload is accepted and the document finishes processing with status `skipped`. ## Rate Limits API requests are rate-limited to ensure fair usage: - 60 requests per minute per API key - 10 document uploads per minute (POST /v1/documents) Rate limit information is included in every response using the standard `RateLimit-*` headers: ``` RateLimit-Limit: 60 RateLimit-Remaining: 55 RateLimit-Reset: 42 ``` `RateLimit-Reset` is the number of seconds until the current window resets. A `429` response additionally includes a `Retry-After` header (seconds) and a `retryAfter` field in the JSON body. ## Handling Rate Limits When you receive a `429` response, wait for the number of seconds indicated by the `Retry-After` header before retrying. Implement exponential backoff for robustness: ``` async function fetchWithRetry(url, options, maxRetries = 3) { for (let i = 0; i setTimeout(r, Math.max(retryAfter * 1000, 1000))); continue; } return response; } throw new Error("Rate limit exceeded after retries"); } ``` ## Common Error Scenarios | Error | Cause | Solution | | --- | --- | --- | | "Invalid or missing API key" | Missing `Authorization` header or malformed key. | Check your API key format and header. | | "Insufficient scope" | API key doesn't have the required scope. | Update key scopes in Settings > API Keys. | | "Access denied to this space" | API key is restricted and can't access the requested space. | Add the space to the key's allowed spaces or use a key with broader access. | | "Document not found" | Document doesn't exist or is in an inaccessible space. | Verify the document ID and your key's space access. | | "File content does not match any supported format" | Uploaded file bytes don't match PDF, JPEG, PNG, TIFF, HEIC, or Office document signatures. | Ensure you're uploading a valid file in a supported format. | | "Content-Type mismatch" | The Content-Type header doesn't match the actual file content. | Set the correct Content-Type for your file or let your HTTP client detect it. | --- ## Playground URL: https://paperarchive.io/docs/api/playground Interactive playground for the Paperarchive REST API. Test endpoints with your own API key, inspect responses live, and copy ready-to-paste curl examples.