Batch upload

Add up to 50 documents in one call.

Base URL https://futuresmart.ai/document-intelligence/api · every request sends x-api-key. Samples read the key from DOCUMENT_INTELLIGENCE_API_KEY. All endpoints

Get upload URLs for many files

POST/v1/{knowledge_id}/upload-urls/batch

Generate presigned S3 URLs for multiple files in a single request. Returns a batch_id for tracking.

Credential Document Intelligence API key (x-api-key)

Path parameters

Name	Type	Description
`knowledge_id`required	`string`

Request body · application/json

Name	Type	Description
`files`required	`array<BatchUploadFileRequest>`	List of files to generate upload URLs for (1-50 items)
`↳ file_name`required	`string`	Name of the file
`↳ content_type`required	`string`	MIME type of the file
`user_id`	`string \| null`	User identifier (optional)

Response · 200

Name	Type	Description
`uploads`required	`array<BatchUploadFileResponse>`	List of upload URLs for each file
`↳ object_id`required	`string`	Unique object identifier for the file
`↳ file_name`required	`string`	Name of the file
`↳ presigned_url`required	`string`	Presigned URL for uploading the file
`↳ download_presigned_url`required	`string`	Presigned URL for downloading the file

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/document-intelligence/api"
API_KEY = os.environ["DOCUMENT_INTELLIGENCE_API_KEY"]

r = requests.post(
    f"{API_ROOT}/v1/YOUR_COLLECTION_ID/upload-urls/batch",
    headers={"x-api-key": API_KEY},
    json={
        "files": [{
            "file_name": "<file_name>",
            "content_type": "<content_type>",
        }],
    },
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/document-intelligence/api";

const res = await fetch(`${API_ROOT}/v1/YOUR_COLLECTION_ID/upload-urls/batch`, {
  method: "POST",
  headers: { "x-api-key": process.env.DOCUMENT_INTELLIGENCE_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "files": [
      {
        "file_name": "<file_name>",
        "content_type": "<content_type>"
      }
    ]
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X POST "https://futuresmart.ai/document-intelligence/api/v1/YOUR_COLLECTION_ID/upload-urls/batch" \
  -H "x-api-key: $DOCUMENT_INTELLIGENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "file_name": "<file_name>",
        "content_type": "<content_type>"
      }
    ]
  }'

Example request body

JSON

{
  "files": [
    {
      "file_name": "<file_name>",
      "content_type": "<content_type>"
    }
  ]
}

Response shape (200)

JSON

{
  "uploads": [
    {
      "object_id": "<object_id>",
      "file_name": "<file_name>",
      "presigned_url": "<presigned_url>",
      "download_presigned_url": "<download_presigned_url>"
    }
  ]
}

Add many documents

POST/v1/{knowledge_id}/documents/batch

Process multiple files with shared configuration. All files inherit identical processing settings.

Can process files via direct upload (files parameter) or via URLs (file_urls parameter). Files can be uploaded via batch_upload_urls endpoint first, then their URLs are provided here for processing.

All configuration parameters are provided as form fields. If not provided, default values will be used.

Credential Document Intelligence API key (x-api-key)

Path parameters

Name	Type	Description
`knowledge_id`required	`string`

Request body · multipart/form-data (optional)

Name	Type	Description
`files`	`array<file> \| null`	Optional collection of files to upload and process
`file_urls`	`string \| null`	Comma-separated file URLs to process
`enable_chunking`	`boolean`	Enable chunking (default: true)Default: true
`use_llama_parse`	`boolean \| null`	Deprecated — use document_processing_mode. Defaults to None so 'not sent' stays distinguishable from an explicit false.
`document_processing_mode`	`string \| null`	What the documents' content is like: auto (default — reads locally and detects), text_based, scanned, layout_aware, visual, or mixed. Applies to every file in the batch.One of: `auto`, `text_based`, `scanned`, `layout_aware`, `visual`, `mixed`
`chunk_size`	`integer`	Chunk size for processing (default: 2000)Default: 2000
`transcript_provider`	`TranscribeUsing`	Transcript provider: 'openai' or 'groq' (default: 'openai')One of: `openai`, `groq`Default: openai

Response · 200

Name	Type	Description
`batch_id`required	`string`	Unique batch identifier
`status`required	`string`	Batch status: 'processing' if any document is being processed, 'failed' if all failed
`message`required	`string`	Status message
`documents`required	`array<BatchDocumentStatus>`	List of documents with their status
`↳ object_id`required	`string`	Object identifier for the document
`↳ file_name`required	`string`	File name of the document
`↳ status`required	`string`	Processing status of the document
`↳ processing_duration_ms`	`number \| null`	Processing duration in milliseconds (completed_at - created_at)
`↳ error_detail`	`string \| null`	Error detail if status is 'failed'

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/document-intelligence/api"
API_KEY = os.environ["DOCUMENT_INTELLIGENCE_API_KEY"]

r = requests.post(
    f"{API_ROOT}/v1/YOUR_COLLECTION_ID/documents/batch",
    headers={"x-api-key": API_KEY},
    data={"files": "<files>", "file_urls": "<file_urls>", "enable_chunking": "<enable_chunking>", "use_llama_parse": "<use_llama_parse>", "document_processing_mode": "<document_processing_mode>", "chunk_size": "<chunk_size>", "transcript_provider": "<transcript_provider>"},
    timeout=120,
)
r.raise_for_status()
print(r.json())

import { readFile } from "node:fs/promises";

const API_ROOT = "https://futuresmart.ai/document-intelligence/api";

const form = new FormData();
form.append("files", "<files>");
form.append("file_urls", "<file_urls>");
form.append("enable_chunking", "<enable_chunking>");
form.append("use_llama_parse", "<use_llama_parse>");
form.append("document_processing_mode", "<document_processing_mode>");
form.append("chunk_size", "<chunk_size>");
form.append("transcript_provider", "<transcript_provider>");

const res = await fetch(`${API_ROOT}/v1/YOUR_COLLECTION_ID/documents/batch`, {
  method: "POST",
  headers: { "x-api-key": process.env.DOCUMENT_INTELLIGENCE_API_KEY },
  body: form,
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X POST "https://futuresmart.ai/document-intelligence/api/v1/YOUR_COLLECTION_ID/documents/batch" \
  -H "x-api-key: $DOCUMENT_INTELLIGENCE_API_KEY" \
  -F "files=<files>" \
  -F "file_urls=<file_urls>" \
  -F "enable_chunking=<enable_chunking>" \
  -F "use_llama_parse=<use_llama_parse>" \
  -F "document_processing_mode=<document_processing_mode>" \
  -F "chunk_size=<chunk_size>" \
  -F "transcript_provider=<transcript_provider>"

Response shape (200)

JSON

{
  "batch_id": "<batch_id>",
  "status": "<status>",
  "message": "<message>",
  "documents": [
    {
      "object_id": "<object_id>",
      "file_name": "<file_name>",
      "status": "<status>"
    }
  ]
}

Get a batch's status

GET/v1/{knowledge_id}/batch/{batch_id}/status

Check processing status for all documents in a batch. Returns aggregated counts and individual document statuses.

Credential Document Intelligence API key (x-api-key)

Path parameters

Name	Type	Description
`knowledge_id`required	`string`
`batch_id`required	`string`	Batch identifier

Response · 200

Name	Type	Description
`batch_id`required	`string`	Unique batch identifier
`total`required	`integer`	Total number of documents in the batch
`completed`required	`integer`	Number of completed documents
`processing`required	`integer`	Number of documents currently processing
`failed`required	`integer`	Number of failed documents
`documents`required	`array<BatchDocumentStatus>`	List of documents with their status
`↳ object_id`required	`string`	Object identifier for the document
`↳ file_name`required	`string`	File name of the document
`↳ status`required	`string`	Processing status of the document
`↳ processing_duration_ms`	`number \| null`	Processing duration in milliseconds (completed_at - created_at)
`↳ error_detail`	`string \| null`	Error detail if status is 'failed'
`elapsed_since_created_ms`	`number \| null`	Milliseconds elapsed from batch creation to now

Other responses

422 Validation Error

import os
import requests

API_ROOT = "https://futuresmart.ai/document-intelligence/api"
API_KEY = os.environ["DOCUMENT_INTELLIGENCE_API_KEY"]

r = requests.get(
    f"{API_ROOT}/v1/YOUR_COLLECTION_ID/batch/YOUR_BATCH_ID/status",
    headers={"x-api-key": API_KEY},
    timeout=120,
)
r.raise_for_status()
print(r.json())

const API_ROOT = "https://futuresmart.ai/document-intelligence/api";

const res = await fetch(`${API_ROOT}/v1/YOUR_COLLECTION_ID/batch/YOUR_BATCH_ID/status`, {
  method: "GET",
  headers: { "x-api-key": process.env.DOCUMENT_INTELLIGENCE_API_KEY },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log(await res.json());

curl -X GET "https://futuresmart.ai/document-intelligence/api/v1/YOUR_COLLECTION_ID/batch/YOUR_BATCH_ID/status" \
  -H "x-api-key: $DOCUMENT_INTELLIGENCE_API_KEY"

Response shape (200)

JSON

{
  "batch_id": "<batch_id>",
  "total": 0,
  "completed": 0,
  "processing": 0,
  "failed": 0,
  "documents": [
    {
      "object_id": "<object_id>",
      "file_name": "<file_name>",
      "status": "<status>"
    }
  ]
}