fact_search

curl --request POST \
  --url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/fact-search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "<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
  }
}

fact_search

Run the fixed single-shot search pipeline over a workspace. Cost class: job.

One retrieval pass (hybrid search, plus the knowledge graph when the workspace has one, fused when both legs return candidates), targeted page reads or retrieved passages for prose (specialized engines for tables or images), then one answering pass — so it returns in seconds where deep-search may take minutes. The caller receives a 202 with a queued :class:~ndi_service.app.platform_api.results.Job and polls GET /jobs/{id} for the :class:~ndi_service.app.platform_api.results.IntelligentSearchResult — the identical result shape deep-search lands, evidences and coverage included.

Single-shot: a fact-search run keeps no conversation, so the result’s session_id is always null and the request body has no session_id field. For a thread you can ask follow-ups in, call deep-search. It always answers — the result carries a direct grounded answer plus interpretation, the pipeline’s reading of the query — and never asks back: the body has no allow_clarification either (a fixed pipeline has no agent who could pose the question).

Retrieval only: this job never grounds. To pin a quote to a region of its source document, call document-operations ground on the file the evidence names (source_file_id) with its quote as the target text.

POST

workspaces

{workspace_id}

fact-search

fact_search

curl --request POST \
  --url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/fact-search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "<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

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

application/json

Body for POST /workspaces/{workspace_id}/fact-search — always the fixed pipeline.

Deliberately no session_id: a fact-search run is single-shot and keeps no conversation, so the strict base rejects the field outright instead of a bespoke validator explaining why it cannot be honored. No effort either — the fixed pipeline has no budget presets. And no allow_clarification: the pipeline has no agent who could ask back, so it always answers — the strict base rejects the field, same as the removed include_answer.

query

string

required

Required string length: 1 - 4096

context

string | null

Maximum string length: 20000

path_prefix

string | null

top_k

integer | null

How many evidences to return, best first. Omitted means 6. It is a cap on the answer's citation list, not on how much the pipeline reads: retrieval width is fixed, so a larger top_k returns more of what was already found rather than searching further. Raising it far above the default trades citation count for reliability — the whole list is one constrained generation, and the ceiling is 50.

Required range: 1 <= x <= 50

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

fact_search

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response