Uploading Files

Docuworm supports two ingestion paths:

Users upload files directly in the widget UI.
Your application uploads files programmatically with helper APIs.

Use both in production.

Extraction support matrix

File type	Extraction support
PDF (`application/pdf`)	Supported
Text MIME types (`text/*`)	Supported
Images (`image/jpeg`, `image/png`, `image/webp`, `image/gif`)	Supported
Other MIME types	Upload may succeed, but text extraction can fail

If extraction fails, the file will not be useful as searchable context.

The widget includes a file upload control in the chat input and sources tab.

Programmatic uploads (Vanilla baseline)

import {
  uploadFile,
  uploadFileFromUrl,
  uploadFileFromBlob,
  uploadFilesOnReady,
} from "https://cdn.docuworm.ai/docuworm.js";

const widget = document.querySelector("docuworm-chat");

// File object
await uploadFile(file, widget);

// Public or presigned URL (must be browser-fetchable)
await uploadFileFromUrl("https://example.com/statement.pdf", widget, {
  filename: "statement.pdf",
});

// Blob / ArrayBuffer / base64 / data URL
await uploadFileFromBlob(blobOrBufferOrBase64, {
  filename: "notes.txt",
  mimeType: "text/plain",
}, widget);

// Mixed batch
await uploadFilesOnReady([
  file,
  "https://example.com/guide.pdf",
  blob,
], widget);

Queueing behavior

Upload helpers can be called before thread initialization. The widget queues work and processes it as soon as the thread is ready.

React

const widgetRef = useRef<HTMLElement | null>(null);

async function preload(urls: string[]) {
  if (!widgetRef.current) return;
  await uploadFilesOnReady(urls, widgetRef.current);
}

Vue

const widget = ref<HTMLElement | null>(null);

async function preload(urls: string[]) {
  if (!widget.value) return;
  await uploadFilesOnReady(urls, widget.value);
}

Svelte

<script lang="ts">
  let widget: HTMLElement | null = null;

  async function preload(urls: string[]) {
    if (!widget) return;
    await uploadFilesOnReady(urls, widget);
  }
</script>

URL upload requirements

When using uploadFileFromUrl():

URL must be reachable from the browser.
CORS and auth on your storage URL must allow browser fetch.
Prefer short-lived presigned URLs for private documents.

Failure handling pattern

try {
  await uploadFile(file, widget);
} catch (error) {
  console.error("Upload failed", error);
}