Documents

Add documents, follow their processing, and remove them.

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 an upload URL

POST/v1/{knowledge_id}/upload-url

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

Path parameters

Name	Type	Description
`knowledge_id`required	`string`

Request body · application/x-www-form-urlencoded

Name	Type	Description
`file_name`required	`string`
`content_type`required	`string`

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-url",
    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/upload-url`, {
  method: "POST",
  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 POST "https://futuresmart.ai/document-intelligence/api/v1/YOUR_COLLECTION_ID/upload-url" \
  -H "x-api-key: $DOCUMENT_INTELLIGENCE_API_KEY"

List documents

GET/v1/{knowledge_id}/documents

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

Path parameters

Name	Type	Description
`knowledge_id`required	`string`

Query parameters

Name	Type	Description
`content_type`	`string \| null`
`metadata_filter`	`string \| null`	Optional JSON-encoded metadata filter dict
`include_source_id`	`boolean`	When true (with metadata_filter), return [{object_id, source_id}] instead of bare object_idsDefault: false
`include_metadata`	`boolean`	When true (with metadata_filter), return [{object_id, metadata}] with full payload inline in a single call (avoids per-doc metadata fetches)Default: false
`limit`	`integer \| null`	Max docs for the filtered path (default 15; raise for full-folder reconcile sweeps)
`match_all`	`boolean`	Optional. false (default) = loose OR (match at least one), preserving legacy behavior; true = strict AND (every metadata_filter field must match, e.g. to scope by space_id)Default: false

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/documents",
    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/documents`, {
  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/documents" \
  -H "x-api-key: $DOCUMENT_INTELLIGENCE_API_KEY"

Add a document

POST/v1/{knowledge_id}/documents

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
`text`	`string \| null`
`file`	`file \| null`
`file_url`	`string \| null`
`weblink`	`string \| null`
`use_llama_parse`	`boolean \| null`
`document_processing_mode`	`string \| null`	What the document's content is like: auto (default — reads locally and detects), text_based, scanned, layout_aware, visual, or mixed. Ignored for plain text content, which has no scanned/layout/visual dimension. For a weblink it applies two ways: a URL that resolves to a file (PDF/DOCX/plain text) picks LlamaParse settings, exactly like an uploaded file; a URL that resolves to an HTML page picks the scraper (auto/text_based/scanned -> Newspaper, layout_aware/visual/mixed -> FireCrawl with boilerplate-stripping off) — see fs-agent-workers/docs/plan/document-processing/archive/design-weblink-modes.md for the full table. Omit to inherit the legacy use_llama_parse behaviour.One of: `auto`, `text_based`, `scanned`, `layout_aware`, `visual`, `mixed`
`transcript_provider`	`TranscribeUsing`	One of: `openai`, `groq`Default: openai
`scrape_using`	`ScrapeUsing`	Deprecated, no effect. The scraper is now chosen from document_processing_mode.One of: `Newspaper`, `FireCrawl`Default: FireCrawl
`scraping_method`	`ScrapingMethod`	One of: `scrape`, `crawl`Default: scrape
`max_depth`	`integer \| null`	Default: 1
`chunk_size`	`integer \| null`	Default: 2000
`enable_chunking`	`boolean \| null`	Default: true
`extra_metadata`	`string \| null`	Optional JSON string of arbitrary key-value metadata

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",
    headers={"x-api-key": API_KEY},
    data={"text": "<text>", "file": "<file>", "file_url": "<file_url>", "weblink": "<weblink>", "use_llama_parse": "<use_llama_parse>", "document_processing_mode": "<document_processing_mode>", "transcript_provider": "<transcript_provider>", "scrape_using": "<scrape_using>", "scraping_method": "<scraping_method>", "max_depth": "<max_depth>", "chunk_size": "<chunk_size>", "enable_chunking": "<enable_chunking>", "extra_metadata": "<extra_metadata>"},
    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("text", "<text>");
form.append("file", "<file>");
form.append("file_url", "<file_url>");
form.append("weblink", "<weblink>");
form.append("use_llama_parse", "<use_llama_parse>");
form.append("document_processing_mode", "<document_processing_mode>");
form.append("transcript_provider", "<transcript_provider>");
form.append("scrape_using", "<scrape_using>");
form.append("scraping_method", "<scraping_method>");
form.append("max_depth", "<max_depth>");
form.append("chunk_size", "<chunk_size>");
form.append("enable_chunking", "<enable_chunking>");
form.append("extra_metadata", "<extra_metadata>");

const res = await fetch(`${API_ROOT}/v1/YOUR_COLLECTION_ID/documents`, {
  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" \
  -H "x-api-key: $DOCUMENT_INTELLIGENCE_API_KEY" \
  -F "text=<text>" \
  -F "file=<file>" \
  -F "file_url=<file_url>" \
  -F "weblink=<weblink>" \
  -F "use_llama_parse=<use_llama_parse>" \
  -F "document_processing_mode=<document_processing_mode>" \
  -F "transcript_provider=<transcript_provider>" \
  -F "scrape_using=<scrape_using>" \
  -F "scraping_method=<scraping_method>" \
  -F "max_depth=<max_depth>" \
  -F "chunk_size=<chunk_size>" \
  -F "enable_chunking=<enable_chunking>" \
  -F "extra_metadata=<extra_metadata>"

List documents (paginated)

GET/v2/{knowledge_id}/documents

List documents with long-lived presigned URLs (7-day expiry with DB caching).

Supports the Knowledge Upload Status window: search uploaded items by file_name or object_id, and get direct links to both the original uploaded document and its parsed/extracted document. Also backs the Knowledge screen's document table — this endpoint previously returned every matching document in one response with no pagination or sort, which was fine at small counts and wrong at any real one.

Sorted and paginated here in Python, not in SQL: retrieve_chatbot_knowledge_v2 groups crawled sub-pages under their parent document (sub_urls) AFTER fetching every matching row, so a SQL-level OFFSET/LIMIT could split a parent from its own children across pages. Sorting/slicing the already-grouped result keeps every parent with its children on one page — the cost is holding the knowledge base's full filtered document set in memory for the sort, the same tradeoff the v2 tabular data view (get_data_view_tabular_v2) already makes for its multi-field sort. Presigned URLs are generated only for the returned page, not the whole set, so pagination is also what keeps this endpoint's S3 URL-signing cost bounded.

Returns: - source_presigned_url: Presigned URL for original uploaded file (7-day expiry, cached in DB) - extracted_s3_url: Presigned URL for extracted markdown text (7-day expiry) - source: where the document came from — "clickup" for a connector-synced page, otherwise the row's content_type value unchanged ("file" / "url" / "plain_text"). Only "clickup" is new: a synced page is posted through the ordinary file_url path, so content_type calls it a "file" and cannot tell the two apart; the connector's identity survives only in extra_metadata. - document_processing_mode: the mode the document was requested to be read in ("text_based", "scanned", "layout_aware", "visual", "mixed"). Requested, not effective — the worker may auto-shift a mode it finds wrong (an image-only PDF shifts to OCR) and does not report that back to this service. - total_count / current_page / total_pages: pagination metadata

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

Path parameters

Name	Type	Description
`knowledge_id`required	`string`

Query parameters

Name	Type	Description
`content_type`	`string \| null`
`file_name`	`string \| null`	Search uploaded items by file name (case-insensitive partial match)
`object_id`	`string \| null`	Search uploaded items by object ID (case-insensitive partial match)
`page`	`integer`	1-indexed page number.Default: 1
`page_size`	`integer`	Documents per page.Default: 20
`sort_by`	`string`	One of: created_time, file_name, status, updated_time.Default: created_time
`order`	`string`	'asc' or 'desc'.Default: desc

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}/v2/YOUR_COLLECTION_ID/documents",
    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}/v2/YOUR_COLLECTION_ID/documents`, {
  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/v2/YOUR_COLLECTION_ID/documents" \
  -H "x-api-key: $DOCUMENT_INTELLIGENCE_API_KEY"

Delete a document

DELETE/v1/{knowledge_id}/documents/{object_id}

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

Path parameters

Name	Type	Description
`knowledge_id`required	`string`
`object_id`required	`string`

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.delete(
    f"{API_ROOT}/v1/YOUR_COLLECTION_ID/documents/YOUR_DOCUMENT_ID",
    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/documents/YOUR_DOCUMENT_ID`, {
  method: "DELETE",
  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 DELETE "https://futuresmart.ai/document-intelligence/api/v1/YOUR_COLLECTION_ID/documents/YOUR_DOCUMENT_ID" \
  -H "x-api-key: $DOCUMENT_INTELLIGENCE_API_KEY"

Get a document's processing status

GET/v1/{knowledge_id}/documents/{object_id}/status

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

Path parameters

Name	Type	Description
`knowledge_id`required	`string`
`object_id`required	`string`

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/documents/YOUR_DOCUMENT_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/documents/YOUR_DOCUMENT_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/documents/YOUR_DOCUMENT_ID/status" \
  -H "x-api-key: $DOCUMENT_INTELLIGENCE_API_KEY"

Get a document's deletion status

GET/v1/{knowledge_id}/documents/{object_id}/deletion-status

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

Path parameters

Name	Type	Description
`knowledge_id`required	`string`
`object_id`required	`string`

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/documents/YOUR_DOCUMENT_ID/deletion-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/documents/YOUR_DOCUMENT_ID/deletion-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/documents/YOUR_DOCUMENT_ID/deletion-status" \
  -H "x-api-key: $DOCUMENT_INTELLIGENCE_API_KEY"

Get document summaries

POST/v1/{knowledge_id}/documents/summaries

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

Path parameters

Name	Type	Description
`knowledge_id`required	`string`

Query parameters

Name	Type	Description
`query`	`string \| null`	Search query over document summaries
`mode`	`string \| null`	Search mode: 'hybrid' (default, RRF fusion) or 'semantic' (dense-only)Default: hybrid
`metadata_filter`	`string \| null`	Optional JSON-encoded metadata filter dict
`match_all`	`boolean`	Optional. Metadata-only path (no query): false (default) = loose OR; true = strict AND (e.g. to scope by space_id). The search path (query set) already applies filters as AND.Default: false
`limit`	`integer \| null`	Optional limit for number of documents
`include_metadata`	`boolean`	Include document metadata with summariesDefault: false
`include_summary`	`boolean`	Include document summary in response (default: true)Default: true

Request body · application/json (optional)

Name	Type	Description
`object_ids`required	`array<string>`

Response · 200

Name	Type	Description
`summaries`required	`object`

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/summaries",
    headers={"x-api-key": API_KEY},
    json={
        "object_ids": ["<object_ids>"],
    },
    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/documents/summaries`, {
  method: "POST",
  headers: { "x-api-key": process.env.DOCUMENT_INTELLIGENCE_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    "object_ids": [
      "<object_ids>"
    ]
  }),
});
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/summaries" \
  -H "x-api-key: $DOCUMENT_INTELLIGENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "object_ids": [
      "<object_ids>"
    ]
  }'

Example request body

JSON

{
  "object_ids": [
    "<object_ids>"
  ]
}

Response shape (200)

JSON

{
  "summaries": {}
}