Skip to main content
Creating a knowledge document is a three-step flow:

​
Step 1 — Request a presigned URL

POST /api/knowledge/presign
Authorization: Bearer <token>
Content-Type: application/json

{
  "filename": "w9-form.pdf",
  "organization_uid": "org-uuid-here",
  "content_type": "application/pdf"
}
Response (200) 
{
  "message": "Presigned URL generated",
  "data": {
    "presigned_post": {
      "url": "https://bucket.s3.amazonaws.com/",
      "fields": {
        "key": "DEV/org-uuid/pdf/17100.../abc.../w9-form.pdf",
        "Content-Type": "application/pdf",
        "policy": "...",
        "AWSAccessKeyId": "...",
        "signature": "..."
      }
    },
    "knowledge_document_uid": "kd-uuid-here",
    "s3_object_name": "DEV/org-uuid/pdf/17100.../abc.../w9-form.pdf",
    "expires_in": 900
  }
}
Note: The exact fields vary depending on your AWS signature version and credential type. When using temporary credentials (SSO/STS), an x-amz-security-token field is also included. Always iterate over all returned fields dynamically rather than hardcoding field names.

​
Step 2 — Upload file to S3

Build a FormData from the fields object, append the file last, and POST directly to the S3 url. This bypasses your backend entirely. 
const formData = new FormData();
Object.entries(fields).forEach(([key, value]) => formData.append(key, value));
formData.append("file", file); // file must be appended last

await fetch(url, { method: "POST", body: formData });
S3 enforces a maximum file size of 25 MB via the presigned policy. Oversized uploads are rejected by S3 before the bytes are stored.

​
Step 3 — Confirm the upload

POST /api/knowledge/confirm
Authorization: Bearer <token>
Content-Type: application/json

{
  "knowledge_document_uid": "kd-uuid-here",
  "organization_uid": "org-uuid-here"
}
Response (202) 
{
  "message": "Upload confirmed, processing started",
  "data": {
    "knowledge_document_uid": "kd-uuid-here",
    "workflow_id": "knowledge-doc-uuid",
    "status": "processing"
  }
}
The server verifies the S3 object exists, performs a defense-in-depth size check, and starts a background Temporal workflow to create the KnowledgeDocument database record.

​
Supported file types

ExtensionContent Type
PDFapplication/pdf
DOCXapplication/vnd.openxmlformats-officedocument.wordprocessingml.document
XLSXapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet
PNGimage/png
JPG/JPEGimage/jpeg

​
Limits

  • Maximum file size: 25 MB (enforced by S3 policy and server-side verification)
  • Presigned URL expiry: 15 minutes