Sources

Sources represent uploaded documents in the platform. Each source goes through an asynchronous extraction pipeline that converts files into structured derivatives (page texts, markdown, per-page images). Sources are the raw material for knowledge bases: once extracted, their content can be chunked and indexed for semantic search.

Common Patterns

The typical flow: upload a file (POST /api/sources/upload), poll for completion (GET /api/sources/{id} until extraction_status is ‘extracted’ or ‘attention_required’), then retrieve extracted text (GET /api/sources/{id}/page-texts). For files already in project storage, use import-from-storage. For web pages, use import-url. To swap extraction backends after the fact, POST /api/sources/{id}/reextract with a new extraction_model.

GET /api/sources

List all sources with optional status filter.

string

Filter by extraction_status. One of: pending, extracting, extracted, attention_required, failed, cancelled.

response = requests.get(f"{BASE_URL}/api/sources", headers=headers)
print(response.json())

const res = await fetch(`${BASE_URL}/api/sources`, { headers });
const sources = await res.json();

curl '{BASE_URL}/api/sources' \
  -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

POST /api/sources/upload

Upload a file for extraction. Accepts PDF, DOCX, PPTX, XLSX, images (PNG/JPG/WebP/GIF/TIFF), and plain text. Uses multipart/form-data. Optional fields: name (display name), metadata (JSON string, preserved through indexing), extraction_model (PDF only; one of auto, mistral, paddleocr, lighton, opendataloader, fitz, pdfplumber).

with open("file.pdf", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/api/sources/upload",
        headers={"apikey": API_KEY, "Authorization": f"Bearer {API_KEY}"},
        files={"file": ("file.pdf", f, "application/pdf")},
        data={"extraction_model": "mistral"},
    )

const form = new FormData();
form.append("file", blob, "file.pdf");
form.append("extraction_model", "mistral");
const res = await fetch(`${BASE_URL}/api/sources/upload`, {
  method: "POST",
  headers: { apikey: API_KEY, Authorization: `Bearer ${API_KEY}` },
  body: form,
});

curl -X POST '{BASE_URL}/api/sources/upload' \
  -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" \
  -F "file=@file.pdf" \
  -F "extraction_model=mistral"

POST /api/sources/import-from-storage

Import a file already in project storage as a source.

{
  "bucket": "documents",
  "path": "reports/q4.pdf",
  "name": "Q4 Report"
}

response = requests.post(
    f"{BASE_URL}/api/sources/import-from-storage",
    headers=headers,
    json={"bucket": "documents", "path": "reports/q4.pdf"},
)

const res = await fetch(`${BASE_URL}/api/sources/import-from-storage`, {
  method: "POST", headers,
  body: JSON.stringify({ bucket: "documents", path: "reports/q4.pdf" }),
});

curl -X POST '{BASE_URL}/api/sources/import-from-storage' \
  -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"bucket": "documents", "path": "reports/q4.pdf"}'

POST /api/sources/import-url

Import content from web URLs. mode=‘urls’ imports a fixed list, mode=‘crawl’ spiders from a seed URL, mode=‘sitemap’ parses a sitemap XML. Requires Firecrawl API key to be configured in project settings.

{
  "mode": "urls",
  "urls": ["https://example.com/page1", "https://example.com/page2"],
  "max_pages": 50
}

response = requests.post(
    f"{BASE_URL}/api/sources/import-url",
    headers=headers,
    json={"mode": "urls", "urls": ["https://example.com/page1"]},
)

const res = await fetch(`${BASE_URL}/api/sources/import-url`, {
  method: "POST", headers,
  body: JSON.stringify({ mode: "urls", urls: ["https://example.com/page1"] }),
});

curl -X POST '{BASE_URL}/api/sources/import-url' \
  -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"mode": "urls", "urls": ["https://example.com/page1"]}'

GET /api/sources/

Get source details including extraction status.

string

required

Source ID

response = requests.get(f"{BASE_URL}/api/sources/{source_id}", headers=headers)

const res = await fetch(`${BASE_URL}/api/sources/${sourceId}`, { headers });

curl '{BASE_URL}/api/sources/{id}' \
  -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

GET /api/sources//page-texts

Get extracted text content organized by page.

string

required

Source ID

integer

Specific page number

response = requests.get(f"{BASE_URL}/api/sources/{source_id}/page-texts", headers=headers)

const res = await fetch(`${BASE_URL}/api/sources/${sourceId}/page-texts`, { headers });

curl '{BASE_URL}/api/sources/{id}/page-texts' \
  -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

PATCH /api/sources/

Update a source’s display name or metadata.

string

required

Source ID

{
  "name": "New Display Name",
  "metadata": { "author": "alice" }
}

response = requests.patch(f"{BASE_URL}/api/sources/{source_id}", headers=headers, json={"name": "New Display Name"})

const res = await fetch(`${BASE_URL}/api/sources/${sourceId}`, { method: "PATCH", headers, body: JSON.stringify({ name: "New Display Name" }) });

curl -X PATCH '{BASE_URL}/api/sources/{id}' \
  -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Display Name"}'

POST /api/sources//reextract

Re-run extraction on an existing source, optionally with a different extraction_model.

string

required

Source ID

{
  "extraction_model": "paddleocr"
}

response = requests.post(f"{BASE_URL}/api/sources/{source_id}/reextract", headers=headers, json={"extraction_model": "paddleocr"})

const res = await fetch(`${BASE_URL}/api/sources/${sourceId}/reextract`, { method: "POST", headers, body: JSON.stringify({ extraction_model: "paddleocr" }) });

curl -X POST '{BASE_URL}/api/sources/{id}/reextract' \
  -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"extraction_model": "paddleocr"}'

POST /api/sources//cancel

Cancel an in-progress extraction. Sets extraction_status to ‘cancelled’.

string

required

Source ID

response = requests.post(f"{BASE_URL}/api/sources/{source_id}/cancel", headers=headers)

const res = await fetch(`${BASE_URL}/api/sources/${sourceId}/cancel`, { method: "POST", headers });

curl -X POST '{BASE_URL}/api/sources/{id}/cancel' \
  -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

GET /api/sources//download

Download the original uploaded file (as stored in project storage).

string

required

Source ID

response = requests.get(f"{BASE_URL}/api/sources/{source_id}/download", headers=headers)
open("source.pdf", "wb").write(response.content)

const res = await fetch(`${BASE_URL}/api/sources/${sourceId}/download`, { headers });
const blob = await res.blob();

curl '{BASE_URL}/api/sources/{id}/download' -o source.pdf \
  -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

GET /api/sources//derivatives//download

Download a derivative artifact. type is one of: markdown, text, page_text, image. For per-page types (page_text, image) pass index=N (0-based) in the query string.

string

required

Source ID

string

required

Derivative type: markdown, text, page_text, or image

integer

0-based index for per-page derivatives (page_text, image)

response = requests.get(f"{BASE_URL}/api/sources/{source_id}/derivatives/markdown/download", headers=headers)
print(response.text)

const res = await fetch(`${BASE_URL}/api/sources/${sourceId}/derivatives/markdown/download`, { headers });
const text = await res.text();

curl '{BASE_URL}/api/sources/{id}/derivatives/markdown/download' \
  -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

DELETE /api/sources/

Delete a source and its associated storage files (original + derivatives).

string

required

Source ID

response = requests.delete(f"{BASE_URL}/api/sources/{source_id}", headers=headers)

await fetch(`${BASE_URL}/api/sources/${sourceId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/sources/{id}' \
  -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Error Responses

Source routes return {"error": "<message>"}.

Status	Description
400	Upload missing the `file` form field, no filename, or invalid `metadata` JSON
400	Upload or `/import-from-storage`: unsupported file extension (allowed: `.pdf`, `.txt`, `.md`, `.docx`, `.xlsx`, `.xls`, `.pptx`, `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.tiff`)
400	Upload, `/import-from-storage`, or `/reextract`: invalid `extraction_model` (must be one of the configured PDF extraction methods)
400	`/import-from-storage`: missing `bucket` or `path`
400	`/import-url`: missing/invalid `mode` (`urls`/`crawl`/`sitemap`), missing or empty URL list, invalid sitemap URL, or no URLs found in sitemap
400	PATCH: no body or no valid fields to update
400	`/page-texts`: invalid `page` query (must be an integer ≥ 1); `/derivatives/{type}/download`: invalid `index` query
404	No source exists with the given ID; referenced file not found in storage (`/import-from-storage`); requested page or derivative does not exist; no file/derivative available for download
409	`/cancel`: extraction is not in a cancellable state (must be `pending` or `extracting`)
500	Upload, import, extraction, page download, or derivative download failed; body contains the underlying error message

Getting Started

Concepts

Guides

API Reference

Common Patterns

GET /api/sources

POST /api/sources/upload

POST /api/sources/import-from-storage

POST /api/sources/import-url

GET /api/sources/

GET /api/sources//page-texts

PATCH /api/sources/

POST /api/sources//reextract

POST /api/sources//cancel

GET /api/sources//download

GET /api/sources//derivatives//download

DELETE /api/sources/

Error Responses

​Common Patterns

​GET /api/sources

​POST /api/sources/upload

​POST /api/sources/import-from-storage

​POST /api/sources/import-url

​GET /api/sources/

​GET /api/sources//page-texts

​PATCH /api/sources/

​POST /api/sources//reextract

​POST /api/sources//cancel

​GET /api/sources//download

​GET /api/sources//derivatives//download

​DELETE /api/sources/

​Error Responses

Common Patterns

GET /api/sources

POST /api/sources/upload

POST /api/sources/import-from-storage

POST /api/sources/import-url

GET /api/sources/

GET /api/sources//page-texts

PATCH /api/sources/

POST /api/sources//reextract

POST /api/sources//cancel

GET /api/sources//download

GET /api/sources//derivatives//download

DELETE /api/sources/

Error Responses