Upload

documents.create_upload stages bytes for one parse, extract, split, classify, or ground operation. It returns an UploadResponse that can be passed directly as the operation’s source.

A granular upload is temporary and single-use. To keep a file, upload it to a workspace.

Basic usage

from pathlib import Path

from ndi_sdk import NdiClient

with NdiClient() as client:
    upload = client.documents.create_upload(Path("report.pdf"))
    # Returns: UploadResponse with upload_id, file_name, size_bytes,
    # content_hash, and expires_at
    print(upload.upload_id, upload.expires_at)

    queued = client.documents.parse(upload, wait_seconds=30)
    # Returns: Job; the upload is consumed by this operation
    job = client.jobs.wait(queued.job_id, timeout=600)
    # Returns: succeeded Job with a ParseResult
    print(job.result.markdown)

Method signature

def create_upload(
    content: str | Path | bytes | BinaryIO,
    *,
    file_name: str | None = None,
    ttl_seconds: int | None = None,
) -> UploadResponse

Parameters

Parameter	Type	Required	Description
`content`	path string, `Path`, bytes, or binary file	Yes	File contents to stage
`file_name`	`str \| None`	No	Filename to record. Required when `content` does not carry a name
`ttl_seconds`	`int \| None`	No	How long an unused upload remains available. Omit for 24 hours; maximum 7 days

Returns

UploadResponse:

Field	Type	Description
`upload_id`	`UUID`	Temporary handle accepted as a document-operation source
`file_name`	`str`	Recorded filename
`size_bytes`	`int`	Uploaded byte count
`content_hash`	`str`	SHA-256 digest of the staged bytes
`expires_at`	`datetime`	Deletion time if no operation consumes the upload

Upload options

From a path

Use Path when the file is on disk:

from pathlib import Path

from ndi_sdk import NdiClient

with NdiClient() as client:
    upload = client.documents.create_upload(Path("invoice.pdf"))
    # Returns: UploadResponse; file_name is "invoice.pdf"

String filesystem paths are also accepted:

from ndi_sdk import NdiClient

with NdiClient() as client:
    upload = client.documents.create_upload("invoice.pdf")
    # Returns: UploadResponse

From an open binary file

from ndi_sdk import NdiClient

with NdiClient() as client:
    with open("invoice.pdf", "rb") as file:
        upload = client.documents.create_upload(file)
        # Returns: UploadResponse; the open file's name is preserved

From bytes

Raw bytes do not have a filename. Supply one so NDI can select the correct processing lane:

from pathlib import Path

from ndi_sdk import NdiClient

with NdiClient() as client:
    data = Path("invoice.pdf").read_bytes()
    upload = client.documents.create_upload(data, file_name="invoice.pdf")
    # Returns: UploadResponse

Custom unused-upload TTL

from ndi_sdk import NdiClient

with NdiClient() as client:
    upload = client.documents.create_upload(
        "invoice.pdf",
        ttl_seconds=3600,
    )
    # Returns: UploadResponse that expires in one hour if unused

The TTL only bounds an upload that no operation consumes. Once a document operation uses the handle, NDI removes the staged bytes when that job finishes. The handle cannot be reused for another operation.

Use a URL instead

You do not need to call create_upload when NDI can fetch the source directly:

from ndi_sdk import NdiClient, UrlSource

with NdiClient() as client:
    source = UrlSource(
        url="https://example.com/reports/annual-report.pdf",
        file_name="annual-report.pdf",
    )
    job = client.documents.parse(source)
    # Returns: Job

The URL must use HTTPS and be reachable by NDI. For private storage, provide a presigned HTTPS URL. See Sources and uploads.

Async upload

import asyncio
from pathlib import Path

from ndi_sdk import AsyncNdiClient


async def main() -> None:
    async with AsyncNdiClient() as client:
        upload = await client.documents.create_upload(Path("report.pdf"))
        # Returns: UploadResponse
        print(upload.upload_id)


asyncio.run(main())

Limits and formats

The upload endpoint enforces the byte cap configured for your API key and rejects formats that no granular document operation supports. Format support then narrows for the operation that consumes the upload; a file accepted by upload can still be rejected by parse, split, classify, extract, or ground.

Format support

Check which document, image, spreadsheet, email, and media formats each operation accepts.

Errors and limits

Review upload size, rate, concurrency, and request limits.

Error handling

from ndi_sdk import ConflictError, InvalidRequestError, NdiClient

with NdiClient() as client:
    try:
        upload = client.documents.create_upload("report.pdf")
        queued = client.documents.parse(upload)
        # Returns: Job, or raises if the upload cannot be staged or consumed
    except InvalidRequestError as exc:
        print(exc.code, exc.message)
    except ConflictError as exc:
        print(exc.code, exc.message)

Common upload outcomes:

file_too_large (413) — the bytes exceed the upload cap.
zero_byte_file (422) — the staged file is empty.
unsupported_file_type (422) — raised by create_upload when no granular operation supports the format, when the filename conflicts with a conclusive byte signature, or by the consuming operation when that specific operation does not support it.
FileNotFoundError — a local path does not exist; this is raised before an HTTP request.

Consuming operations can return upload_expired (409) for an expired handle or upload_not_found (404) for an unknown, cross-tenant, or already removed handle. These are not raised by create_upload itself. unsupported_file_type is synchronous and non-retryable. A rejection from create_upload creates no upload handle; a rejection from the consuming operation creates no job, so there is nothing to poll with jobs.wait. The service inspects only a bounded byte prefix and treats multipart Content-Type as advisory.

Best practices

Prefer Path objects

Use pathlib.Path for local files so the filename travels with the bytes.

Create near use

Stage a granular upload immediately before its operation. It is a temporary, single-use handle.

Name raw bytes

Always pass file_name with raw bytes so NDI can infer the format.

Use workspaces for persistence

Put files in a workspace when they must survive one operation or become searchable.

Get started

Core methods

Async and utilities

Basic usage

Method signature

Parameters

Returns

Upload options

From a path

From an open binary file

From bytes

Custom unused-upload TTL

Use a URL instead

Async upload

Limits and formats

Format support

Errors and limits

Error handling

Best practices

Prefer Path objects

Create near use

Name raw bytes

Use workspaces for persistence

Next steps

​Basic usage

​Method signature

​Parameters

​Returns

​Upload options

​From a path

​From an open binary file

​From bytes

​Custom unused-upload TTL

​Use a URL instead

​Async upload

​Limits and formats

Format support

Errors and limits

​Error handling

​Best practices

Prefer Path objects

Create near use

Name raw bytes

Use workspaces for persistence

​Next steps

Basic usage

Method signature

Parameters

Returns

Upload options

From a path

From an open binary file

From bytes

Custom unused-upload TTL

Use a URL instead

Async upload

Limits and formats

Error handling

Best practices

Next steps