Skip to main content
POST
automatic_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.

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}/automatic-search.

Single-shot query, optional context and folder scope. The fixed router selects fact, deep, or filtered search before retrieval. Execution settings are resolved by the service; this route has no effort or clarification controls.

​
query
string
required

The question to answer from the workspace. Surrounding whitespace is stripped; a blank query is refused.

Required string length: 1 - 4096
​
context
string | null

Optional free-form background for the model. It does not change access or retrieval scope.

Maximum string length: 20000
​
path_prefix
string | null

Narrow the search to this workspace subtree. Omit to search the whole workspace.

Maximum string length: 1024
​
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

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

​
status
enum<string>
required

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

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

How hard this run worked, for the search kinds that carry it. A consolidated deep-search job (kind deep_search_v2, or a scoped intelligent_search run) echoes the requested level: 'low', 'medium', or 'high'. Historical intelligent_search rows carry the retired internal selector instead: 'fast' is fact-search (and still what new fact-search rows say), 'automatic' is automatic-search, 'deep' (or the legacy 'balanced') is the pre-consolidation deep-search and the console's QA chat — 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.

​
kind
string
default:intelligent_search

Automatic search orchestration job.

Allowed value: "intelligent_search"
​
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 input and result payloads are dropped. Null means they are kept indefinitely.

​
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
AutomaticSearchResult · object | null

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.

Available options:
available,
expired,
not_retained
​
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.

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