Granular vs workspace workflows

​

Granular operations

• Provide a document via POST /v1/uploads, a public URL, or a workspace file reference.
• Call an operation: POST /v1/parse
• Get results: markdown, categories, extracted JSON, or target locations.
• Results include presigned URLs that expire when the job’s payload_expires_at passes.

• You want single-document intelligence without long-term storage.
• You’re analyzing a one-off PDF or spreadsheet.
• You’re integrating document intelligence into an existing pipeline.

curl -X POST "$NDI_BASE_URL/v1/parse" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": {"type": "url", "url": "https://example.com/report.pdf", "file_name": "report.pdf"}}'

​

Workspace workflows

• Create a workspace with a chosen domain and access labels.
• Upload files: POST /v1/workspaces/{workspace_id}/files
• Ingest files to create derivatives: POST /v1/workspaces/{workspace_id}/ingestions
• Query with tools: search, file reading and QA, knowledge graph walk, intelligent search.

• You maintain a corpus of documents (engagement files, reference materials).
• You need to search or query across many files.
• You want to build a knowledge graph of relationships.
• You need to track file history and versions.

# Create workspace (domain_slug identifies the taxonomy vocabulary)
WS=$(curl -s -X POST "$NDI_BASE_URL/v1/workspaces" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "q4-audit", "domain_slug": "generic"}' | jq -r '.workspace_id')

# Upload a file
FILE=$(curl -s -X POST "$NDI_BASE_URL/v1/workspaces/$WS/files" \
  -H "X-API-Key: $NDI_API_KEY" \
  -F "file=@document.pdf" \
  -F 'metadata={"path":"document.pdf"}' | jq -r '.result.file.file_id')

# Wait for upload job to finish, then ingest
JOB=$(curl -s -X POST "$NDI_BASE_URL/v1/workspaces/$WS/ingestions" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"selection\":{\"type\":\"file_ids\",\"file_ids\":[\"$FILE\"]}}" | jq -r '.job_id')

# Poll until ingestion done, then query
curl -X POST "$NDI_BASE_URL/v1/workspaces/$WS/tools/hybrid-search" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "revenue by segment"}'

​

Key differences

​

Shared concepts

• Authentication — X-API-Key header
• Job lifecycle — POST returns 200/202, poll with GET /v1/jobs/{job_id}
• Idempotency — Idempotency-Key header for replay safety
• Errors — typed error codes and messages