upload_file

curl --request POST \
  --url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/files \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form 'file=<string>' \
  --form 'metadata=<string>' \
  --form file.0='@example-file'

{
  "created_at": "2023-11-07T05:31:56Z",
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kind": "parse",
  "status": "queued",
  "deleted_at": "2023-11-07T05:31:56Z",
  "effort": "<string>",
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "detail": {}
  },
  "finished_at": "2023-11-07T05:31:56Z",
  "force": true,
  "idempotency_key": "<string>",
  "name": "<string>",
  "payload_expires_at": "2023-11-07T05:31:56Z",
  "progress": {
    "items_done": 0,
    "items_failed": 0,
    "items_total": 123,
    "stage": "<string>",
    "units_done": 0,
    "units_total": 123
  },
  "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "query": "<string>",
  "query_scope": {
    "type": "workspace"
  },
  "result": {
    "document": {
      "page_count": 123,
      "blocks": [
        {
          "content": "<string>",
          "id": "<string>",
          "type": "<string>",
          "confidence": 123,
          "image_url": "<string>",
          "location": {
            "page": 2,
            "kind": "page_region",
            "polygons": [
              [
                [
                  123,
                  123
                ]
              ]
            ]
          }
        }
      ],
      "chunks": [
        {
          "content": "<string>",
          "id": "<string>",
          "location": {
            "page": 2,
            "kind": "page_region",
            "polygons": [
              [
                [
                  123,
                  123
                ]
              ]
            ]
          }
        }
      ],
      "markdown": "<string>",
      "ocr": {
        "lines": [
          {
            "bbox": {
              "height": 123,
              "left": 123,
              "original_page": 123,
              "page": 123,
              "top": 123,
              "width": 123
            },
            "confidence": 123,
            "text": "<string>",
            "chunk_index": 123,
            "rotation": 0
          }
        ],
        "words": [
          {
            "bbox": {
              "height": 123,
              "left": 123,
              "original_page": 123,
              "page": 123,
              "top": 123,
              "width": 123
            },
            "confidence": 123,
            "text": "<string>",
            "chunk_index": 123,
            "rotation": 0
          }
        ]
      },
      "spreadsheet": {
        "sheets": [
          {
            "cell_map_url": "<string>",
            "sheet_name": "<string>"
          }
        ]
      },
      "text": "<string>"
    },
    "file_name": "<string>",
    "lane": "<string>",
    "ocr_applied": true,
    "units": 123,
    "converted_pdf_url": "<string>",
    "result_type": "parse"
  },
  "result_state": "available",
  "source": {
    "upload_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "upload"
  },
  "started_at": "2023-11-07T05:31:56Z",
  "units": 0,
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "error": {
    "code": "invalid_request",
    "detail": null,
    "message": "Request body has extra fields that this operation does not accept.",
    "request_id": "req-01j9k2n3p4q5r6s7t8v9",
    "retryable": false
  }
}

{
  "error": {
    "code": "invalid_request",
    "detail": null,
    "message": "Request body has extra fields that this operation does not accept.",
    "request_id": "req-01j9k2n3p4q5r6s7t8v9",
    "retryable": false
  }
}

upload_file

Upload a source file into the workspace. Cost class: job.

The one route with two credentials: the tenant’s X-API-Key, or a short-lived X-Upload-Token grant minted by create_upload_grant — which is how a customer’s end client uploads directly without ever holding the key. A grant redeems the multipart path only, within the constraints frozen into it (workspace, optional pinned path, byte cap).

Two content paths, per the UploadFileRequest contract:

multipart/form-data — file bytes in a file part, request parameters as a JSON string in a metadata form field.
application/json — an UploadFileRequest body whose source carries a UrlSource; the bytes are fetched server-side and then take the exact same storage/ledger path as multipart.

Upload does NOT ingest. The file lands with ingestion_status = discovered and is not searchable. Making it searchable requires a separate POST .../ingestions call. This keeps the cost model honest: a caller can upload a thousand files and choose to ingest fifty.

POST

workspaces

{workspace_id}

files

upload_file

curl --request POST \
  --url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/files \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form 'file=<string>' \
  --form 'metadata=<string>' \
  --form file.0='@example-file'

{
  "created_at": "2023-11-07T05:31:56Z",
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kind": "parse",
  "status": "queued",
  "deleted_at": "2023-11-07T05:31:56Z",
  "effort": "<string>",
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "detail": {}
  },
  "finished_at": "2023-11-07T05:31:56Z",
  "force": true,
  "idempotency_key": "<string>",
  "name": "<string>",
  "payload_expires_at": "2023-11-07T05:31:56Z",
  "progress": {
    "items_done": 0,
    "items_failed": 0,
    "items_total": 123,
    "stage": "<string>",
    "units_done": 0,
    "units_total": 123
  },
  "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "query": "<string>",
  "query_scope": {
    "type": "workspace"
  },
  "result": {
    "document": {
      "page_count": 123,
      "blocks": [
        {
          "content": "<string>",
          "id": "<string>",
          "type": "<string>",
          "confidence": 123,
          "image_url": "<string>",
          "location": {
            "page": 2,
            "kind": "page_region",
            "polygons": [
              [
                [
                  123,
                  123
                ]
              ]
            ]
          }
        }
      ],
      "chunks": [
        {
          "content": "<string>",
          "id": "<string>",
          "location": {
            "page": 2,
            "kind": "page_region",
            "polygons": [
              [
                [
                  123,
                  123
                ]
              ]
            ]
          }
        }
      ],
      "markdown": "<string>",
      "ocr": {
        "lines": [
          {
            "bbox": {
              "height": 123,
              "left": 123,
              "original_page": 123,
              "page": 123,
              "top": 123,
              "width": 123
            },
            "confidence": 123,
            "text": "<string>",
            "chunk_index": 123,
            "rotation": 0
          }
        ],
        "words": [
          {
            "bbox": {
              "height": 123,
              "left": 123,
              "original_page": 123,
              "page": 123,
              "top": 123,
              "width": 123
            },
            "confidence": 123,
            "text": "<string>",
            "chunk_index": 123,
            "rotation": 0
          }
        ]
      },
      "spreadsheet": {
        "sheets": [
          {
            "cell_map_url": "<string>",
            "sheet_name": "<string>"
          }
        ]
      },
      "text": "<string>"
    },
    "file_name": "<string>",
    "lane": "<string>",
    "ocr_applied": true,
    "units": 123,
    "converted_pdf_url": "<string>",
    "result_type": "parse"
  },
  "result_state": "available",
  "source": {
    "upload_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "upload"
  },
  "started_at": "2023-11-07T05:31:56Z",
  "units": 0,
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "error": {
    "code": "invalid_request",
    "detail": null,
    "message": "Request body has extra fields that this operation does not accept.",
    "request_id": "req-01j9k2n3p4q5r6s7t8v9",
    "retryable": false
  }
}

{
  "error": {
    "code": "invalid_request",
    "detail": null,
    "message": "Request body has extra fields that this operation does not accept.",
    "request_id": "req-01j9k2n3p4q5r6s7t8v9",
    "retryable": false
  }
}

Authorizations

X-API-Key

string

header

required

Headers

Idempotency-Key

string | null

Replaying a request with the same key returns the original job with 200, never a second job.

Maximum string length: 200

Path Parameters

workspace_id

string<uuid>

required

Workspace identifier.

Query Parameters

wait_seconds

integer

default:0

Bounded inline wait. 0 (the default) returns 202 immediately. Above 0 the route returns 200 with a terminal job if the work finished in time, and 202 with the still-running job if it did not. Either way, read status.

Required range: 0 <= x <= 300

Body

multipart/form-data

file

file | null

metadata

string | null

JSON-encoded UploadFileRequest. Required for multipart uploads.

Response

Successful Response

Every slow method returns one of these (spec 12 §1.4).

There is no /parse + /parse_async pair: every job-creating route returns 202 with a queued job and accepts ?wait_seconds=, returning 200 with a terminal job if the work finished inside the window. The caller's code path is the same either way — read status.

created_at

string<date-time>

required

job_id

string<uuid>

required

kind

enum<string>

required

What a job is doing. Open enum — a new member is additive.

Available options:

parse,

split,

classify,

categorize,

extract,

ground,

ingestion,

reconciliation,

kg_build,

file_upload,

file_replace,

upload_session_complete,

file_delete,

workspace_delete,

intelligent_search,

qa_file,

qa_tables,

filtered_search,

je_testing,

deep_search_v2

status

enum<string>

required

cancelled is a first-class terminal status, not a failed variant.

Conflating them makes error-rate metrics lie and forces every client to string-match an error code.

Available options:

queued,

running,

succeeded,

failed,

cancelled

deleted_at

string<date-time> | null

When the caller hid this run from listings, via delete_job. A soft delete: the job still reads by id and still counts toward GET /v1/usage — what it stops doing is appearing in GET /v1/jobs.

effort

string | null

Which implementation ran this job, for the one kind whose request carries an effort (intelligent_search): 'fast' is fact-search, 'deep' (or the legacy 'balanced') is deep-search and the console's QA chat — a deep-search run under another surface, not a fourth implementation, so this field cannot tell those two apart. Null for every other kind. Read from the stored request, so it rides the same retention path as query and result: null once result_state leaves available.

error

Error · object | null

Present only on failed.

Show child attributes

finished_at

string<date-time> | null

force

boolean | null

The request's own force flag, echoed regardless of outcome. Present for kinds whose request carries one (e.g. kg_build, where a true value cleared the durable store before the job ran) so a caller can tell that apart from a build that failed leaving the prior store untouched — result alone cannot, since it is absent on failure either way.

idempotency_key

string | null

name

string | null

Caller-chosen display name (the console's 'project'). Mutable via PATCH /v1/jobs/{job_id}.

payload_expires_at

string<date-time> | null

progress

JobProgress · object | null

Absent until running.

Show child attributes

project_id

string<uuid> | null

Caller-minted grouping id shared by jobs submitted together. Filterable on GET /v1/jobs.

query

string | null

The question this job was asked, for the search kinds that carry one (intelligent_search, qa_file, qa_tables, filtered_search); null for every other kind. Read from the stored request, so it rides the same retention path as result: null once result_state leaves available. Narrow by design — the frozen access context never reaches the wire. File scope is summarised separately as query_scope.

query_scope

WorkspaceQueryScope · object

The question ran against the whole workspace.

WorkspaceQueryScope
FileQueryScope
PathPrefixQueryScope
FilesQueryScope

Show child attributes

result

ParseResult · object

Present only on succeeded, and only while retained.

Show child attributes

result_state

enum<string>

default:available

Why Job.result is null.

available with a null result means the job has not succeeded yet; expired means retention dropped it; not_retained means the client is provisioned zero_retention and already had its one chance to read it. A late poll returns the job with a state, never a 404 — "this expired" and "this never existed" are a scheduling problem and a bug respectively, and a 404 makes them identical.

Available options:

available,

expired,

not_retained

source

UploadSource · object

Bytes staged through POST /v1/uploads. Single-use, TTL-bound.

UploadSource
UrlSource
WorkspaceFileSource
ParseResultSource

Show child attributes

started_at

string<date-time> | null

units

integer

default:0

workspace_id

string<uuid> | null

The workspace this job reads. Null for a document operation whose source is an upload, a URL, or a prior parse result.

Conventions

Granular operations

Catalog

Workspaces and files

Ingestion and graph

Tools and search

Jobs and usage

upload_file

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response