Skip to main content
POST
deep_search

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. The key is kept with the job for replay and never cleared, so it must not contain personal data.

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}/deep-search — every agentic search.

Every run uses one configuration (see :mod:~ndi_service.app.platform_api.intelligent_search.effort), so no body field selects a model, a tool surface, a reasoning budget, or an effort level. effort, use_kg and include_answer stay on the body only because published SDK, CLI and MCP releases still send them (see :data:RetiredEffort): deprecated, accepted, and ignored. tier never shipped in a published client and stays rejected by the strict base.

Scope never changes the configuration (NDI-573): every run — scoped by paths/path_prefix or not — gets the same source-level configuration. The folder and file selectors resolve to one file set that every tool enforces server-side against the stored job.

​
query
string
required

What to answer, in the caller's own words. Stripped before its length is checked; a blank query is refused rather than run.

Required string length: 1 - 4096
​
allow_clarification
boolean
default:false

Let the agent finish the run with clarifying questions instead of an answer, when the query is genuinely ambiguous and the ambiguity materially changes the answer. The result then carries the questions in clarification_questions (and as text in clarification), with answer and reasoning null and evidences empty; answer them in the same thread via the result's session_id, with clarification_answers or a follow-up query. Off, the default, means the agent always answers with its best reading, stated in the answer.

​
clarification_answers
ClarificationAnswer · object[] | null

Answers to the clarifying questions this thread's last turn asked (its result's clarification_questions): one entry per question, in order. Send them with that turn's session_id and its query; the agent then answers that query with the answers applied, and sees which answer belongs to which of its questions. Any other follow-up query in the thread works too — this field is the structured way to answer. Cannot be combined with allow_clarification: a run answering questions does not ask again.

Required array length: 1 - 2 elements
​
context
string | null

Free-form background for the model — the engagement, the entity, what the caller already knows. It informs the answer; it does not widen or narrow which files the caller may see.

Maximum string length: 20000
​
effort
enum<string> | null
deprecated

Deprecated and ignored: the service resolves the run's configuration itself. Accepted so clients released before the effort levels were retired keep working; omit it.

Available options:
high,
medium,
low
​
include_answer
boolean | null
deprecated

Deprecated and ignored: every run answers. Accepted so clients released before it was retired keep working; omit it.

​
output_schema
Output Schema · object | null

A JSON Schema (Draft 2020-12, object root, local non-recursive $ref only, no pattern, patternProperties or unevaluated*) the answer must follow. When set, the agent writes answer as JSON text conforming to it, the run checks that and asks the agent to correct a mismatch, and the result carries the parsed value in structured_answer. A field the source does not state comes back null, whatever type the schema gives it. Explanation goes to reasoning where the result has one, and evidences are unchanged. If the answer still misses the schema, the run succeeds with answer as written and structured_answer null. Omit for a prose answer.

​
path_prefix
string | null

Put every uploaded file under one folder subtree, workspace-relative, in the run's scope; paths, where the body takes it, adds more files. Omit both for the whole workspace.

​
paths
string[] | null

Scope the run to exactly these uploaded files. Every retrieval tool the agent runs — search, listings, reads, table queries, the shell — sees only these files and the content ingested from them; everything else is invisible to the run. Each entry names an uploaded source file (never a folder — scope folders with path_prefix; the two add up, so the run covers the folder's files plus these). No limit on how many. Unknown or inaccessible paths are refused up front.

Minimum array length: 1
Required string length: 1 - 1024
​
session_id
string<uuid> | null

Continue a prior deep-search conversation: the id echoed on an earlier result's session_id. With the same folder/file scope and access grants, the agent resumes that thread's context. A changed scope or grants starts a fresh conversation and returns a new session_id; older threads without a scope snapshot also restart. Omit to start a new thread. Only the API key that started the thread may continue it; a thread whose turn is still running returns 409 session_busy.

​
surface
enum<string>
default:deep_search

Which console history this run belongs to. It does not pick the agent, the chassis, or the engine: an omitted value is deep_search (the public API and the Deep Search page). The NDI console sends qa or workbook so Activity and thread lists can split those skins. A follow-up (session_id) inherits the thread head's surface; a conflicting value on the follow-up body is ignored.

Available options:
deep_search,
qa,
workbook
​
use_kg
boolean | null
deprecated

Deprecated and ignored: the service decides whether the knowledge graph is consulted. Accepted so clients released before it was retired keep working; omit it.

Response

Successful Response

The consolidated deep-search route's response shape.

One route, one public effort knob, one implementation: every new run — scoped or not — lands the source-level deep_search_v2 result (answer plus SQL receipts). intelligent_search stays in the kind union only so jobs created by the retired classic loop remain readable via GET /jobs; result_type inside the result repeats the discriminator, so a caller reading only the result payload can still tell them apart.

​
created_at
string<date-time>
required

When the job row was created.

​
job_id
string<uuid>
required

Server-minted id. Poll GET /v1/jobs/{job_id} or pass wait_seconds on create.

​
kind
enum<string>
required

deep_search_v2, the source-level agent — every new run, scoped or not. intelligent_search appears only on deep-search jobs created before the 2026-09 consolidation retired the classic scoped loop; those stay readable here.

Available options:
intelligent_search,
deep_search_v2
​
status
enum<string>
required

Lifecycle: queued, running, succeeded, failed, or cancelled.

Available options:
queued,
running,
succeeded,
failed,
cancelled
​
cost
JobCost · object | null

Final USD component prices under the sheet pinned at acceptance; null before finalization or when no dollar sheet was configured. Does not change legacy credit billing.

​
credit_schedule_version
integer | null

Version of the credit schedule credits were priced under. Null until usage_final is true.

​
credits
integer | null

Final credits billed for this job, priced once under credit_schedule_version. Null until usage_final is true. Never changes afterwards, including after payload expiry or deletion. For a job that failed or was cancelled, the credits for results already delivered before it ended (a progressive classify or extract publishes before it finishes); 0 when it delivered nothing. Always null on a stage job that Automatic Search delegated: its work is billed on the parent job.

​
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

How hard this run worked, for the search kinds that carry it. A deep-search job (kind deep_search_v2) created before the effort knob was removed echoes its requested level: 'low', 'medium', or 'high'; newer deep-search jobs, which all run one configuration, read null. An intelligent_search row carries an internal selector instead: 'fast' is fact-search, 'automatic' is automatic-search, and 'deep' (or the legacy 'balanced') is a deep-search or console QA chat job created before the 2026-09 consolidation — those two are not distinguishable by this field. 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

Typed failure envelope when status is failed. Null on any other status.

​
finished_at
string<date-time> | null

When the job reached a terminal status.

​
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

Key that was replayed to return this job. Absent when the create call had no Idempotency-Key.

​
name
string | null

Display name (the console's 'project'). Public Parse, Split, Classify, Extract, and Ground runs supply a stable server default when blank; citation-generated Ground jobs are excluded. mutable via PATCH /v1/jobs/{job_id}.

​
payload_expires_at
string<date-time> | null

When the job's inputs, outputs and processing files are removed. Once the job finishes this is no later than 48 hours after it on a paid account and 7 days after on a free one, or sooner if the workspace's job_ttl_days says so. Null while a job with no job_ttl_days bound is still running, or when the account keeps no job content (zero retention).

​
progress
JobProgress · object | null

Live progress while the job is running. Null while queued and after the job finishes.

​
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.

​
result
IntelligentSearchResult · object

Present only on succeeded, and only while retained.

​
result_state
enum<string>
default:available

Why result may be null. available with a null result means the job has not succeeded yet; expired and not_retained mean the payload was dropped by retention; cancelled means the job, or the job it ran for, was cancelled, so no result is served (a cancelled job is charged only for results delivered before the cancel).

Available options:
available,
expired,
not_retained,
cancelled
​
source
UploadSource · object

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

​
started_at
string<date-time> | null

When execution began. Null while still queued.

​
surface
enum<string> | null

Which console history this deep-search job belongs to. deep_search is the public route and the Deep Search page; qa and workbook are the console chat skins over the same agent. It does not pick the implementation. Null for fact-search and every non-deep-search kind. Jobs stored before this field existed echo deep_search. Read from the stored payload, so it rides the same retention path as query.

Available options:
deep_search,
qa,
workbook
​
units
integer
default:0

Billable units once the job finishes; 0 while queued or running. Kept for compatibility: credits is the authoritative billed amount.

​
usage
JobUsage · object | null

What credits were charged for: one line per part (the parse, the tool's own work), with the quantity, rate and multiplier behind each. Null until usage_final is true, and on jobs finalized before usage breakdowns were introduced.

​
usage_final
boolean
default:false

True once credits is final and will not change. False while the job is queued or running, and until any cleanup of its delegated stages has been accounted for. A failed tool job (read_file, run_sql, hybrid_search, grep, file_metadata, folder_metadata) created with an Idempotency-Key stays false for one hour after it fails, because a retry with the same key re-runs it; after that hour it is final and the retry returns the stored error.

​
usage_finalized_at
string<date-time> | null

When credits became final. Null until usage_final is true.

​
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.