Search

The box at the top of a workspace, under File search in the sidebar, asks one question of its files and answers it once. It reads only files that are Ready.

From code, the same search is POST /v1/workspaces/{workspace_id}/automatic-search. Every example below is a whole request for a workspace you created and ingested; see the Python, TypeScript and CLI pages for the SDK and CLI details.

curl "https://console.nace.ai/v1/workspaces/$WORKSPACE_ID/automatic-search?wait_seconds=60" \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What were total liabilities at year end?",
    "path_prefix": "reports/2025",
    "mode": "agent"
  }'

How it runsCopy Anchor Link

A search creates a job, like the tools: ?wait_seconds (0 to 60; more waits 60) works the same way, an Idempotency-Key lets an identical retry return the original job (use a new key when the question, mode or other inputs change), the answer is 200 when the job finishes within the wait and 202 otherwise, and you read the result as in Jobs and results.

Automatic searches are limited to 60 per account every 10 minutes. Past that, a request is refused with 429 rate_limited before any job is created: wait the retry-after seconds it gives, then send it again.

SettingsCopy Anchor Link

In the dashboard, these are the workspace's Settings tab, beside the box, and the folder choice in the box. Each applies to every search from the box and is saved for the workspace. From code, each is an option of the request.

WorkspaceCopy Anchor Link

Which workspace to search. In the dashboard, a workspace's own box searches that workspace. From code, the workspace is in the URL, as its workspace_id.

# The workspace is in the URL: its workspace_id
WORKSPACE_ID=<workspace_id>

curl "https://console.nace.ai/v1/workspaces/$WORKSPACE_ID/automatic-search?wait_seconds=60" \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "What were total liabilities at year end?" }'

FolderCopy Anchor Link

Whole workspace is the default. Pick one folder the files sit in from the list, or type or paste a path.

curl "https://console.nace.ai/v1/workspaces/$WORKSPACE_ID/automatic-search?wait_seconds=60" \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What were total liabilities at year end?",
    "path_prefix": "reports/2025"
  }'

ModeCopy Anchor Link

Which search runs.

curl "https://console.nace.ai/v1/workspaces/$WORKSPACE_ID/automatic-search?wait_seconds=60" \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What were total liabilities at year end?",
    "mode": "fact"
  }'

While a search runs, the dashboard says what it is doing and, in Auto, which route it chose. The route chosen for a question can differ between similar questions, so pick Fast or Agent (Deep in the dashboard) when you know which you want: Fast for a stated fact, Agent for anything that needs reading, calculating or listing.

Add contextCopy Anchor Link

Background the search should know. In the dashboard this is Background in Settings, and every search from the workspace uses it.

curl "https://console.nace.ai/v1/workspaces/$WORKSPACE_ID/automatic-search?wait_seconds=60" \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What were total liabilities at year end?",
    "context": "Entity: Acme Holdings Ltd. Fiscal year ends 30 June."
  }'

Structured outputCopy Anchor Link

A JSON Schema the answer must follow. In the dashboard this is Answer format, in Settings. A schema that is not a JSON object blocks the search until you fix or clear it.

curl "https://console.nace.ai/v1/workspaces/$WORKSPACE_ID/automatic-search?wait_seconds=60" \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What were total liabilities at year end?",
    "output_schema": {"type": "object", "properties": {"total_liabilities": {"type": "number"}, "currency": {"type": "string"}}}
  }'

The answer then also comes back as JSON in structured_answer.

The root must be an object; wrap a list as {"items": [...]}. $ref may only point inside the schema, and not back at itself. pattern, patternProperties, unevaluatedProperties and unevaluatedItems are refused: describe a format in description instead.

The answer is checked against the schema and corrected when it misses. structured_answer then holds the parsed value: output.structured_answer for a fact answer, output.answer.structured_answer for the agent. If the answer still misses the schema, the job succeeds with structured_answer: null and the text in answer. Read structured_answer, not answer. output_schema never changes the route.

More options from codeCopy Anchor Link

A request takes two more options and two query settings that the dashboard doesn't expose:

curl "https://console.nace.ai/v1/workspaces/$WORKSPACE_ID/automatic-search?wait_seconds=60" \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Idempotency-Key: liabilities-fy25" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What were total liabilities at year end?",
    "paths": ["contracts/acme-msa.pdf"],
    "top_k": 10
  }'

The answerCopy Anchor Link

A finished search shows these, each a field of the job's result:

On an agent answer, the same fields sit under output.answer; see Fact answers and Agent answers for every field.

For the question above, a fast answer looks like this:

{
  "result_type": "automatic_search",
  "routing": { "selected": "fact", "final": "fact", "reason": "One stated figure from the statements." },
  "output": {
    "result_type": "intelligent_search",
    "answer": "Total liabilities were 4,215,300 USD at 31 December 2025.",
    "confidence": "high",
    "evidences": [
      {
        "source_path": "reports/2025/annual-report.pdf",
        "page": 12,
        "quote": "Total liabilities 4,215,300",
        "relevance": "States total liabilities at year end."
      }
    ],
    "grounding_job_ids": ["c41d7e2a-9b3f-4c6d-8e1a-2b3c4d5e6f70"]
  }
}

In the dashboard, that is the answer with its route and High confidence, and one passage from annual-report.pdf, page 12. The example leaves out fields that are null or not shown; see Fact answers and Agent answers for the full result.

Fact answersCopy Anchor Link

output.result_type is "intelligent_search". A fact search reads once and answers in seconds.

Agent answersCopy Anchor Link

output.result_type is "automatic_agent". The agent reads documents, writes SQL over tables and lists matching documents, for as long as the question needs. Its answer is in output.answer:

Evidences (citations)Copy Anchor Link

Every answer cites the passages it rests on. The API calls them evidences; the dashboard shows them as the numbered evidence beside the answer. Each one is an object in output.evidences:

Phrases of the answer that rest on evidence are underlined, with the evidence's number after them. Select one to mark that evidence and open its file at the passage. The underlines come a moment after the answer, once its phrases are matched to the evidence; an answer that has not been matched reads without them.

Each passage is then looked for in its file: it shows Locating while that runs, then Located or Not located. Select a passage or a row to open its file at that page; a located passage is highlighted there.

From code, whether you get those locations depends on the route that answered:

This applies to a search in Auto mode that the service sent to the agent too, so check routing.final, not the mode you sent. See Quote locations.

Follow-upsCopy Anchor Link

A search runs once and keeps no conversation.

Catalog tablesCopy Anchor Link

When the agent answers a filter, rank or count question by listing documents, such as "invoices over 10,000 from Q4", it adds a catalog table: output.catalog in automatic search, catalog in QA.

The table holds its first rows only. To see more, narrow the question or the scope.

CoverageCopy Anchor Link

• Files withheld: on a fact answer and a catalog table, coverage.restricted_candidates counts matching files the search wasn't allowed to read. 0 means nothing was withheld.
• What was answered: on an agent answer, answer.coverage has one entry per thing the question asked for, with a status of answered, partial or unanswerable, and missing_inputs saying what kept it from a full answer.

ErrorsCopy Anchor Link

Every other error is on Errors.

Coming back to itCopy Anchor Link

The open search is part of the page address, so a reload or a shared link opens the same answer. The Searches tab lists the workspace's recent searches, and Usage › Logs links to each one. An answer stays until explicit deletion. From code, read a search again with GET /v1/documents/jobs/{job_id}.

Searches are limited to 60 per account every 10 minutes.

Next stepsCopy Anchor Link

Keep the workspace's files current with Workspace files, or locate a quote exactly with Ground.