Docs / Uploading Documents

Uploading Documents

Documents are the core of aqoon. Upload files, paste text, or provide URLs — aqoon extracts the content, splits it into searchable chunks, and indexes everything for fast retrieval.

Supported Formats

Source type Accepted formats Max size
PDF .pdf 50 MB
Word Document .docx, .doc 50 MB
Image .png, .jpg, .jpeg 50 MB
Markdown .md 50 MB
Text File .txt 50 MB
Spreadsheet .csv, .xlsx, .xls 50 MB
Web URL Any publicly accessible URL —
Plain Text Paste text directly —

How to Upload

  1. Open a collection and click Upload
  2. Enter a title for the document
  3. Select a file — the source type is auto-detected from the file extension (PDF, Word Document, Image, Markdown, Text, Spreadsheet), or select manually for Plain Text paste or Web URL
  4. Depending on the type:
    • File uploads — Drag and drop or click to browse
    • URL — Paste the web address
    • Plain Text — Type or paste your content
  5. Optionally add tags (comma-separated) to help organize and filter later
  6. Click Upload

Uploading Multiple Files

You can upload multiple files at once. Select several files from the file picker or drag and drop them together.

  • Each file's source type is auto-detected from its extension
  • Titles are generated automatically from filenames (for Markdown files, the first # heading is used instead)
  • Tags are applied to all files in the batch
  • Unsupported or oversized files are skipped with a warning

What Happens After Upload

After you upload a document, aqoon processes it automatically:

  1. Pending — Document is queued for processing
  2. Processing — Text is being extracted (OCR for images, parsing for PDFs/DOCX, fetching for URLs)
  3. Indexed — Content has been split into chunks, embedded, and added to the search index

If something goes wrong, the status shows Failed with an error message. Common causes include corrupted files or inaccessible URLs.

Processing typically takes a few seconds for text and small files. Large PDFs or image-heavy documents may take longer.

Viewing a Document

Click any document title to see its detail page, which shows:

  • Full metadata (title, source type, file size, upload date)
  • Tags as badges
  • The extracted text content
  • A list of all chunks created during processing, with their index and a content preview

Downloading Files

You can download the original file for any document that was uploaded as a file (PDF, DOCX, image, etc.). Text-only and URL documents have no stored file and cannot be downloaded.

Web UI

On the document detail page, click the Download button. The button is hidden for text-only or URL documents.

API

GET /api/v1/documents/{uuid}/download/
curl -L -H "Authorization: Bearer aqn_..." \
  https://aqoon.ai/api/v1/documents/<document-uuid>/download/ \
  -o file.pdf

Python SDK

url = client.get_download_url("document-uuid")

JavaScript SDK

const url = await client.getDownloadUrl(uuid);

The endpoint returns a 302 redirect to a signed Azure Blob Storage URL. Use -L in curl to follow the redirect. The URL is valid for 1 hour. Returns 404 for documents with no stored file.

Deleting a Document

On the document detail page, click Delete to remove the document and all its chunks from the search index. This cannot be undone.

Uploading via API

You can upload documents programmatically using the REST API. Any API key with write permission can upload to the collection it was issued for.

Endpoint

POST /api/v1/collections/{uuid}/documents/

Authentication

Authorization: Bearer aqn_...

The API key must have write permission on the target collection.

Single file upload (curl)

curl -X POST https://aqoon.io/api/v1/collections/<collection-uuid>/documents/ \
  -H "Authorization: Bearer aqn_..." \
  -F "files=@report.pdf"

Batch upload — multiple files in one request (curl)

curl -X POST https://aqoon.io/api/v1/collections/<collection-uuid>/documents/ \
  -H "Authorization: Bearer aqn_..." \
  -F "files=@report.pdf" \
  -F "files=@notes.docx" \
  -F "files=@data.csv"

Python SDK

client.upload_document(collection_uuid, "path/to/file.pdf")

JavaScript SDK

await client.uploadDocument(collectionUuid, file);

Supported file types

PDF (.pdf), Word documents (.docx, .doc), images (.png, .jpg, .jpeg), spreadsheets (.csv, .xlsx, .xls), Markdown (.md), and plain text (.txt).

Async processing

Uploaded documents start with a status of pending and are processed in the background. Poll the document status using:

GET /api/v1/documents/{uuid}/

The status field progresses through pending → processing → indexed. A status of failed means processing encountered an error.

Tip: Instead of polling, you can configure a webhook to receive a notification when processing completes. Set up a webhook URL via POST /api/v1/webhooks/ and aqoon will POST a signed payload to your URL on document.indexed and document.failed events.

Bulk Delete

On the collection detail page, owners can delete multiple documents at once using checkboxes.

  • Each document row has a checkbox on the left — only visible to collection owners
  • The Select All checkbox in the table header selects or deselects all documents on the current page
  • Once one or more documents are checked, a Delete Selected button appears showing the count of selected documents
  • Clicking Delete Selected opens a confirmation dialog before any deletion takes place
  • Confirmed deletions are soft-deleted — documents are removed from the collection list and their search index entries are removed immediately

Bulk delete is only available to collection owners. Subscribers see the document list without checkboxes.

Replacing a Document

When a document's content changes, you can replace the file without losing the original UUID or breaking any integrations that reference it. The old search index entries are removed and the new file is processed from scratch.

Web UI

On the document detail page, click Replace. The form pre-fills the existing title and tags. Select the new file and click Upload. The document returns to pending status while it is re-processed.

API

POST /api/v1/documents/{uuid}/replace/
curl -X POST https://aqoon.io/api/v1/documents/<document-uuid>/replace/ \
  -H "Authorization: Bearer aqn_..." \
  -F "file=@updated-report.pdf" \
  -F "title=Annual Report 2026"

Python SDK

doc = client.replace_document("document-uuid", "path/to/new_file.pdf")

JavaScript SDK

const doc = await client.replaceDocument(uuid, file);

Key behaviours:

  • UUID is preserved — existing references remain valid
  • Old chunks and search index entries are removed before re-processing
  • Title and tags are kept unless explicitly overridden in the request
  • The new file is processed asynchronously: pending → processing → indexed
  • Requires write permission on the collection (same as upload)