cancel_job

cancel_job

curl --request POST \
  --url https://ndi-api.nace.ai/v1/jobs/{job_id}/cancel \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "reason": "<string>"
}
'

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

POST

jobs

{job_id}

cancel

cancel_job

curl --request POST \
  --url https://ndi-api.nace.ai/v1/jobs/{job_id}/cancel \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "reason": "<string>"
}
'

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

Path Parameters

job_id

string<uuid>

required

Job identifier.

Body

application/json

Body for POST /jobs/{job_id}/cancel.

reason is stored in the job's error payload so an audit trail records who cancelled and why. It is surfaced to the caller on the next poll rather than lost.

reason

string | null

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

Authorizations

Path Parameters

Body

Response