Skip to main content
Every job starts with a file object in the request body: 
{
  "file": {
    "source_url": "...",
    "file_name": "annual-report.pdf"
  }
}
source_url accepts three schemes. Upload the document once with POST /upload, then pass the returned handle everywhere: 
{ "file": { "source_url": "ndi://file/7f4d2a10-3b7e-4c25-9f61-8f0f4f0a1b2c" } }
  • Upload once, use many times — the same handle works across parse, ground, and categorize.
  • file_name is optional; it defaults to the name captured at upload.
  • Handles expire after ~6 days (the exact expires_at is returned by the upload). Using an expired handle returns 410 Gone; a handle from another tenant returns 404.

​
https:// — public or presigned URLs

If the document is already reachable over HTTPS (a public URL or a presigned URL from your own storage), point NDI at it directly: 
{
  "file": {
    "source_url": "https://your-bucket.s3.amazonaws.com/report.pdf?X-Amz-...",
    "file_name": "report.pdf"
  }
}
Constraints, all enforced server-side:
  • HTTPS only. Plain http:// is rejected — document links carry your data and must be encrypted in transit.
  • Publicly reachable hosts only. IP-literal hosts, localhost, and private-network addresses are rejected (422).
  • No redirects. The URL must serve the bytes directly.
  • Maximum download: 1 GiB.
  • file_name is required — NDI uses its extension to detect the format.

​
s3:// — direct S3 URLs

Available to tenants with a bring-your-own-bucket storage arrangement, and for referencing artifacts NDI previously produced for you (e.g. passing a prior parse’s markdown_url back into ground or categorize). file_name is required. If your account uses NDI-managed storage, arbitrary s3:// inputs are rejected — use uploads or https:// URLs instead.

​
Supported formats

The format is inferred from the file extension of file_name (or the uploaded file’s name). An unsupported extension fails fast with a 422 before any job is started.
MethodSupported extensions
parse.csv .doc .docm .docx .eml .htm .html .jpeg .jpg .log .msg .pdf .png .ppt .pptx .tif .tiff .txt .vsd .vsdx .webp .xls .xlsm .xlsx .xml
categorizesame as parse
groundsame as parse, minus .eml .msg .vsd .vsdx, plus .bmp .jsonl .md .mdx

​
Upload limits and lifetime

LimitValue
Maximum upload size200 MB (413 when exceeded)
Upload handle lifetime~6 days (see expires_at in the upload response)

​
Result artifacts

Job results reference produced artifacts (markdown files, cropped match images) by URL. For standard accounts these are time-limited download URLs valid for 1 hour. Fetch them promptly, or call GET /jobs/{job_id} again at any time to receive freshly signed URLs — the underlying artifacts persist.