delete_file

curl --request DELETE \
  --url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/files/{file_id} \
  --header 'X-API-Key: <api-key>'

{
  "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
  }
}

delete_file

Soft-delete a file and run the cross-representation cascade as a job.

The file is soft-deleted (deleted_at stamped) so lineage questions stay answerable after the cascade. The cascade job then retires index documents and output rows, drops the sibling folder from storage, cancels in-flight ingestion jobs that name the file, and independently re-checks every representation. DeleteFileResult.counts exist so this is auditable rather than assumed, and verified: false is a failed cascade that must alert.

DELETE

workspaces

{workspace_id}

files

{file_id}

delete_file

curl --request DELETE \
  --url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/files/{file_id} \
  --header 'X-API-Key: <api-key>'

{
  "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

file_id

string<uuid>

required

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

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

delete_file

Authorizations

Headers

Path Parameters

Query Parameters

Response