> ## Documentation Index > Fetch the complete documentation index at: https://docs.ndi.nace.ai/llms.txt > Use this file to discover all available pages before exploring further. # qa > Ask a question about a workspace, as one turn of a conversation. Cost class: **job**. Every turn runs the automatic search agent on its own — no router, no fixed pipeline. It opens with what a search of the workspace finds for the turn, answers straight from that when it already holds the answer, and otherwise reads documents, queries tables, and selects documents from the metadata catalog until it can. Every tool enforces the caller's access and the conversation's scope: ``path_prefix`` and ``paths`` resolve to one file set. Pass a result's ``session_id`` to ask a follow-up: the agent resumes the conversation, so "and for 2023?" or "why?" means what it means in context. When a question is genuinely ambiguous the agent may ask back instead (``allow_clarification``, on by default): the result then carries ``clarification_questions`` with ``answer`` null; reply with ``clarification_answers`` and the same ``session_id``, or rephrase. The result is the agent's answer — citations, SQL receipts, confidence — plus, when it answered from a catalog query, the catalog table, whose ``next_cursor`` continues through ``filtered-search``. ## OpenAPI ````yaml /openapi.json post /v1/workspaces/{workspace_id}/qa openapi: 3.1.0 info: description: >- Document intelligence: parse, split, classify, extract, and ground files, or build a searchable workspace. Authenticate with ``X-API-Key``. title: NDI Platform API version: 0.1.0 servers: - url: https://ndi-api.nace.ai security: [] tags: [] paths: /v1/workspaces/{workspace_id}/qa: post: tags: - intelligent-search summary: qa description: >- Ask a question about a workspace, as one turn of a conversation. Cost class: **job**. Every turn runs the automatic search agent on its own — no router, no fixed pipeline. It opens with what a search of the workspace finds for the turn, answers straight from that when it already holds the answer, and otherwise reads documents, queries tables, and selects documents from the metadata catalog until it can. Every tool enforces the caller's access and the conversation's scope: ``path_prefix`` and ``paths`` resolve to one file set. Pass a result's ``session_id`` to ask a follow-up: the agent resumes the conversation, so "and for 2023?" or "why?" means what it means in context. When a question is genuinely ambiguous the agent may ask back instead (``allow_clarification``, on by default): the result then carries ``clarification_questions`` with ``answer`` null; reply with ``clarification_answers`` and the same ``session_id``, or rephrase. The result is the agent's answer — citations, SQL receipts, confidence — plus, when it answered from a catalog query, the catalog table, whose ``next_cursor`` continues through ``filtered-search``. operationId: qa_v1_workspaces__workspace_id__qa_post parameters: - description: Workspace identifier. in: path name: workspace_id required: true schema: description: Workspace identifier. format: uuid title: Workspace Id type: string - description: >- 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`. in: query name: wait_seconds required: false schema: default: 0 description: >- 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`. maximum: 300 minimum: 0 title: Wait Seconds type: integer - description: >- 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. in: header name: Idempotency-Key required: false schema: anyOf: - maxLength: 200 type: string - type: 'null' description: >- 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. title: Idempotency-Key requestBody: content: application/json: schema: $ref: '#/components/schemas/QaRequest' required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/QaJob' description: Successful Response '504': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Gateway Timeout default: content: application/json: example: error: code: invalid_request detail: null message: >- Request body has extra fields that this operation does not accept. request_id: req-01j9k2n3p4q5r6s7t8v9 retryable: false schema: $ref: '#/components/schemas/ErrorEnvelope' description: >- Typed error envelope used by every 4xx and 5xx. ``error.code`` distinguishes the failure; HTTP status is a consequence of the code. security: - APIKeyHeader: [] components: schemas: QaRequest: additionalProperties: false description: >- Body for ``POST /workspaces/{workspace_id}/qa`` — one turn of a question-answering conversation. Each turn runs the automatic search agent alone: no router and no fact pipeline, so the agent itself decides whether what its opening search found already answers the turn or whether to read and compute further. No model, effort or tool-surface field: the service resolves the configuration. properties: allow_clarification: default: true description: >- Let the agent ask instead of guessing when a question is genuinely ambiguous and the reading materially changes the answer. Such a turn's result carries the questions in `clarification_questions` with `answer` null; reply in the same conversation with `clarification_answers` or a rephrased query. A turn that sends `clarification_answers` never asks again. On by default; off means the agent always answers with its best reading, stated in the answer. title: Allow Clarification type: boolean clarification_answers: anyOf: - items: $ref: '#/components/schemas/ClarificationAnswer' maxItems: 2 minItems: 1 type: array - type: 'null' description: >- Answers to the clarifying questions this conversation's last turn asked, one 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. title: Clarification Answers context: anyOf: - maxLength: 20000 type: string - type: 'null' description: >- 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. title: Context output_schema: anyOf: - additionalProperties: $ref: '#/components/schemas/JsonValue' type: object - type: 'null' description: >- 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. Applies only to the turn that sends it: to keep structured answers across a conversation, send it on every turn, including a reply to clarifying questions. A turn that asks clarifying questions returns them with `structured_answer` null. title: Output Schema path_prefix: anyOf: - type: string - type: 'null' description: >- 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. title: Path Prefix paths: anyOf: - items: maxLength: 1024 minLength: 1 type: string minItems: 1 type: array - type: 'null' description: >- Scope the conversation to exactly these uploaded files. Every tool the agent runs sees only these files and the content ingested from them. Each entry names an uploaded source file (never a folder — scope folders with path_prefix; the two add up). Unknown or inaccessible paths are refused up front. title: Paths query: description: >- What to answer, in the caller's own words. Stripped before its length is checked; a blank query is refused rather than run. maxLength: 4096 minLength: 1 title: Query type: string session_id: anyOf: - format: uuid type: string - type: 'null' description: >- Continue a conversation: the `session_id` echoed on an earlier turn's result. With the same folder/file scope and access grants the agent resumes the conversation, so a follow-up can lean on what was already asked and answered; a changed scope or grants starts a fresh conversation and returns a new `session_id`. Omit to start one. Only the API key that started it may continue it; a conversation whose turn is still running returns 409 session_busy. title: Session Id required: - query title: QaRequest type: object QaJob: additionalProperties: false description: >- One turn of a ``qa`` conversation: the automatic search agent's job, answered or asking back. properties: cost: anyOf: - $ref: '#/components/schemas/JobCost' - type: 'null' description: >- 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. created_at: description: When the job row was created. format: date-time title: Created At type: string credit_schedule_version: anyOf: - type: integer - type: 'null' description: >- Version of the credit schedule `credits` were priced under. Null until `usage_final` is true. title: Credit Schedule Version credits: anyOf: - type: integer - type: 'null' description: >- 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. title: Credits deleted_at: anyOf: - format: date-time type: string - type: 'null' description: >- 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`. title: Deleted At effort: anyOf: - type: string - type: 'null' description: >- 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`. title: Effort error: anyOf: - $ref: '#/components/schemas/Error' - type: 'null' description: >- Typed failure envelope when status is failed. Null on any other status. finished_at: anyOf: - format: date-time type: string - type: 'null' description: When the job reached a terminal status. title: Finished At force: anyOf: - type: boolean - type: 'null' description: >- 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. title: Force idempotency_key: anyOf: - type: string - type: 'null' description: >- Key that was replayed to return this job. Absent when the create call had no Idempotency-Key. title: Idempotency Key job_id: description: >- Server-minted id. Poll GET /v1/jobs/{job_id} or pass wait_seconds on create. format: uuid title: Job Id type: string kind: const: automatic_agent default: automatic_agent description: The automatic search agent, which answers every QA turn. title: Kind type: string name: anyOf: - type: string - type: 'null' description: >- 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}. title: Name payload_expires_at: anyOf: - format: date-time type: string - type: 'null' description: >- 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). title: Payload Expires At progress: anyOf: - $ref: '#/components/schemas/JobProgress' - type: 'null' description: >- Live progress while the job is running. Null while queued and after the job finishes. project_id: anyOf: - format: uuid type: string - type: 'null' description: >- Caller-minted grouping id shared by jobs submitted together. Filterable on GET /v1/jobs. title: Project Id query: anyOf: - type: string - type: 'null' description: >- 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`. title: Query query_scope: anyOf: - discriminator: mapping: file: '#/components/schemas/FileQueryScope' files: '#/components/schemas/FilesQueryScope' path_prefix: '#/components/schemas/PathPrefixQueryScope' workspace: '#/components/schemas/WorkspaceQueryScope' propertyName: type oneOf: - $ref: '#/components/schemas/WorkspaceQueryScope' - $ref: '#/components/schemas/FileQueryScope' - $ref: '#/components/schemas/PathPrefixQueryScope' - $ref: '#/components/schemas/FilesQueryScope' - type: 'null' description: >- Where this search ran, summarised for history UIs: the whole workspace, one file path, one folder prefix, or a count of files. Null for non-query jobs, filtered-search page continuations, and once `result_state` leaves `available`. Never lists multiple filenames, never the raw request, and never the frozen API-key id. title: Query Scope result: anyOf: - $ref: '#/components/schemas/AutomaticAgentResult' - type: 'null' description: Present only on succeeded, and only while retained. result_state: $ref: '#/components/schemas/ResultState' default: available description: >- 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). source: anyOf: - discriminator: mapping: parse_result: '#/components/schemas/ParseResultSource' upload: '#/components/schemas/UploadSource' url: '#/components/schemas/UrlSource' workspace_file: '#/components/schemas/WorkspaceFileSource' propertyName: type oneOf: - $ref: '#/components/schemas/UploadSource' - $ref: '#/components/schemas/UrlSource' - $ref: '#/components/schemas/WorkspaceFileSource' - $ref: '#/components/schemas/ParseResultSource' - type: 'null' description: >- What this job read, for the document operations that take a single `source` (parse, split, classify, extract, ground); null for every other kind. Together with `workspace_id` this is what lets a caller re-open the document a past run was about — a `workspace_file` source stays readable after the run, while an `upload` is single-use and its bytes are gone. Read from the stored request, so it rides the same retention path as `query` and `result`: null once `result_state` leaves `available`. title: Source started_at: anyOf: - format: date-time type: string - type: 'null' description: When execution began. Null while still queued. title: Started At status: $ref: >- #/components/schemas/ndi_service__app__platform_api__contracts__JobStatus description: 'Lifecycle: queued, running, succeeded, failed, or cancelled.' surface: anyOf: - enum: - deep_search - qa - workbook type: string - type: 'null' description: >- 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`. title: Surface units: default: 0 description: >- Billable units once the job finishes; 0 while queued or running. Kept for compatibility: `credits` is the authoritative billed amount. title: Units type: integer usage: anyOf: - $ref: '#/components/schemas/JobUsage' - type: 'null' description: >- 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: default: false description: >- 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. title: Usage Final type: boolean usage_finalized_at: anyOf: - format: date-time type: string - type: 'null' description: When `credits` became final. Null until `usage_final` is true. title: Usage Finalized At workspace_id: anyOf: - format: uuid type: string - type: 'null' description: >- The workspace this job reads. Null for a document operation whose source is an upload, a URL, or a prior parse result. title: Workspace Id required: - job_id - status - created_at title: QaJob type: object ErrorEnvelope: description: Every non-2xx body on ``/v1``. example: error: code: invalid_request detail: null message: Request body has extra fields that this operation does not accept. request_id: req-01j9k2n3p4q5r6s7t8v9 retryable: false properties: error: $ref: '#/components/schemas/Error' required: - error title: ErrorEnvelope type: object ClarificationAnswer: additionalProperties: false description: >- The user's answer to one clarifying question a run asked instead of answering. properties: answer: anyOf: - maxLength: 4096 minLength: 1 type: string - type: 'null' description: >- The answer: one of the question's `options`, or your own words. Null skips the question; the agent then uses its best judgment and states the assumption in its answer. title: Answer question: description: >- The question being answered, as the asking result's `clarification_questions[].question` states it. maxLength: 4096 minLength: 1 title: Question type: string required: - question title: ClarificationAnswer type: object JsonValue: {} JobCost: additionalProperties: false description: An immutable USD price independent of the legacy credit schedule. properties: currency: const: USD default: USD title: Currency type: string lines: description: >- The independently priced Parse and operation components, including paid reuse. items: $ref: '#/components/schemas/CostLine' title: Lines type: array pricing_version: description: The dollar price-sheet version pinned when this job was accepted. title: Pricing Version type: string total_usd: description: Sum of the component amounts in USD, serialized as a decimal string. pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,9}0*$ title: Total Usd type: string required: - pricing_version - total_usd - lines title: JobCost type: object Error: description: The error object, per spec 12 §1.8. properties: code: $ref: '#/components/schemas/ErrorCode' detail: anyOf: - additionalProperties: true type: object - type: 'null' description: Structured payload, when the code carries one. title: Detail message: description: Human- and model-readable; says what to do differently. title: Message type: string request_id: anyOf: - type: string - type: 'null' description: >- Per-request correlation id; matches the ``X-Request-Id`` header. Null only when the error was minted outside any HTTP request, e.g. by a worker. title: Request Id retryable: description: Whether retrying the identical request could succeed. title: Retryable type: boolean required: - code - message - retryable title: Error type: object JobProgress: additionalProperties: false description: Absent until the job is ``running``. properties: items_done: default: 0 title: Items Done type: integer items_failed: default: 0 description: >- Quarantined after exhausting retries, for batch kinds. Excluded from items_done. title: Items Failed type: integer items_total: anyOf: - type: integer - type: 'null' description: Files, for batch kinds. title: Items Total knowledge_graph: anyOf: - $ref: '#/components/schemas/KnowledgeGraphBuildProgress' - type: 'null' description: Detail only a kg_build reports; null for every other job kind. routing: anyOf: - $ref: '#/components/schemas/AutomaticSearchRouting' - type: 'null' description: >- The route an automatic search chose, from the moment it chose it, so a caller can show the decision while the chosen pipeline runs; timings arrive with the result's ``routing``. Null for every other job kind. stage: anyOf: - type: string - type: 'null' description: Current pipeline stage, for display only. title: Stage units_done: default: 0 title: Units Done type: integer units_total: anyOf: - type: integer - type: 'null' title: Units Total title: JobProgress type: object FileQueryScope: additionalProperties: false description: The question ran against one workspace-relative file. properties: path: maxLength: 1024 minLength: 1 title: Path type: string type: const: file default: file title: Type type: string required: - path title: FileQueryScope type: object FilesQueryScope: additionalProperties: false description: The question ran against several files; only the count is public. properties: count: minimum: 2 title: Count type: integer type: const: files default: files title: Type type: string required: - count title: FilesQueryScope type: object PathPrefixQueryScope: additionalProperties: false description: The question ran against one folder subtree. properties: prefix: maxLength: 1024 minLength: 1 title: Prefix type: string type: const: path_prefix default: path_prefix title: Type type: string required: - prefix title: PathPrefixQueryScope type: object WorkspaceQueryScope: additionalProperties: false description: The question ran against the whole workspace. properties: type: const: workspace default: workspace title: Type type: string title: WorkspaceQueryScope type: object AutomaticAgentResult: additionalProperties: false description: >- The automatic search agent's answer, plus its published catalog selection when it made one. ``answer`` is a complete source-level deep-search result (citations, SQL receipts, confidence). ``catalog`` is present when the agent answered with a metadata-catalog query: the server re-executed it authoritatively, and its ``next_cursor`` pages through this job. properties: answer: $ref: '#/components/schemas/DeepSearchV2Result' description: The agent's grounded answer. catalog: anyOf: - $ref: '#/components/schemas/FilteredSearchResult' - type: 'null' description: >- The catalog entries the agent selected, when it answered with a catalog query. result_type: const: automatic_agent default: automatic_agent description: Identifies an automatic search agent result. title: Result Type type: string required: - answer title: AutomaticAgentResult type: object ResultState: description: >- 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; ``cancelled`` means the job, or the root job it ran for, was cancelled. A cancelled job serves no results (it is charged only for results delivered before the cancel) — not its own progressive values, and not a delegated child's result. It is a read state only, derived on the wire; no row stores 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. enum: - available - expired - not_retained - cancelled title: ResultState type: string ParseResultSource: additionalProperties: false description: >- A prior Parse job whose parsed artifact can be reused by downstream methods. properties: job_id: description: Succeeded parse job whose artifact should be reused. format: uuid title: Job Id type: string type: const: parse_result default: parse_result title: Type type: string required: - job_id title: ParseResultSource type: object UploadSource: additionalProperties: false description: Bytes staged through ``POST /v1/uploads``. Single-use, TTL-bound. properties: type: const: upload default: upload title: Type type: string upload_id: description: >- Id returned by POST /v1/uploads. Single-use; bytes are deleted after the job. format: uuid title: Upload Id type: string required: - upload_id title: UploadSource type: object UrlSource: additionalProperties: false description: A public or presigned HTTPS location we fetch server-side. properties: file_name: description: Filename to record for the fetched bytes. maxLength: 512 title: File Name type: string type: const: url default: url title: Type type: string url: description: HTTPS URL the service fetches. maxLength: 2048 pattern: ^https:// title: Url type: string required: - url - file_name title: UrlSource type: object WorkspaceFileSource: additionalProperties: false description: >- A file already in a workspace. The single seam between the two contexts: a granular operation may read a workspace file and still write nothing back. The file need **not** be ingested — granular operations read source bytes, not representations. properties: file_id: description: File id from GET /v1/workspaces/{workspace_id}/files. format: uuid title: File Id type: string type: const: workspace_file default: workspace_file title: Type type: string workspace_id: description: Workspace that owns the file. format: uuid title: Workspace Id type: string required: - workspace_id - file_id title: WorkspaceFileSource type: object ndi_service__app__platform_api__contracts__JobStatus: description: >- ``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. enum: - queued - running - succeeded - failed - cancelled title: JobStatus type: string JobUsage: additionalProperties: false description: How a job's final credits were computed. properties: lines: description: >- One line per part. Their credits sum to the job's credits; waived parts remain listed at 0 credits. items: $ref: '#/components/schemas/UsageLine' title: Lines type: array required: - lines title: JobUsage type: object CostLine: additionalProperties: false description: One independently priced part of a perception job. properties: amount_usd: description: >- This line's USD amount: quantity multiplied by unit_price_usd, serialized as a decimal string. pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,9}0*$ title: Amount Usd type: string execution: description: >- The price tier: normal work or verified, billing-eligible tenant reuse; not provider token caching. enum: - fresh - reused title: Execution type: string operation: description: The work this dollar amount pays for. enum: - parse - split - classify - extract - ground title: Operation type: string quantity: description: >- The number of page-equivalents or Ground targets priced by this line. minimum: 0 title: Quantity type: integer reuse_reason: anyOf: - enum: - reused_parse - repeat_of_job type: string - type: 'null' description: Why the lower reuse rate applies; null on a normal-price line. title: Reuse Reason unit: description: 'The quantity''s billing unit: page-equivalent or Ground target.' enum: - page - item title: Unit type: string unit_price_usd: description: >- USD per unit under the job's pinned price sheet, serialized as a decimal string. pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d{0,9}0*$ title: Unit Price Usd type: string required: - operation - quantity - unit - execution - unit_price_usd - amount_usd title: CostLine type: object ErrorCode: description: |- Every error the ``/v1`` surface can return. Clients must treat this as an **open** enum: a new member is an additive change (spec 12 §9), and a client that crashes on an unknown code makes every future error a breaking change. enum: - invalid_request - unsupported_file_type - file_too_large - invalid_schema - invalid_sql - invalid_path_prefix - command_not_permitted - batch_too_large - domain_validation_failed - default_label_required - wait_required_for_zero_retention - ledger_decision_invalid - tenant_required - partner_required - workspace_not_found - file_not_found - job_not_found - upload_not_found - node_not_found - schema_not_found - domain_not_found - session_not_found - access_label_not_found - ledger_understanding_not_found - ledger_table_not_found - tenant_not_found - path_conflict - schema_version_conflict - access_label_name_taken - workspace_name_taken - access_label_in_use - upload_expired - file_not_ingested - workspace_deleting - workspace_not_deletable - ingestion_in_progress - job_not_cancellable - confirmation_required - domain_not_published - domain_in_use - reserved_domain_slug - kg_not_built - kg_build_in_progress - ledger_understanding_in_progress - ledger_understanding_version_outdated - session_busy - tenant_limit_reached - range_not_satisfiable - result_expired - access_denied - tenant_disabled - access_backstop_violation - access_mode_not_implemented - rate_limited - concurrency_limit_reached - quota_exceeded - corrupt_file - zero_byte_file - encrypted_file - csv_dialect_ambiguous - csv_parse_failed - parse_failed - ocr_failed - conversion_failed - sheetless_workbook - unplayable_media - unclassified_pages - job_cancelled - job_timeout - upstream_unavailable - internal_error - unauthorized - not_implemented title: ErrorCode type: string KnowledgeGraphBuildProgress: additionalProperties: false description: >- Where a ``kg_build`` is, beyond what ``stage`` alone can say. A graph build runs for minutes to hours through a fixed sequence of phases, and ``stage`` names only the current one. Turning that into "how far along" otherwise means hard-coding the build engine's phase order in every client — an order that lives in another package and is free to gain a phase. So the position is reported rather than inferred. The counters are deliberately not a percentage. The phases are wildly unequal (extraction is ~60% of a build, and its per-document cost varies 25x with how dense the documents are), so weighting them is a presentation decision, made against measurements, that belongs to whoever is drawing the bar. properties: countable: description: >- Whether items_total/items_done describe this phase. False for the phases that are a single step, which have no unit to count — draw those as indeterminate rather than as a bar stuck at zero. title: Countable type: boolean documents: anyOf: - type: integer - type: 'null' description: >- Documents registered from the corpus, once the registering phase has run. title: Documents mentions: anyOf: - type: integer - type: 'null' description: >- Mentions extracted across the corpus, once the validating phase has run. title: Mentions phase_count: description: >- How many phases a build passes through before it is done. Currently 9. title: Phase Count type: integer phase_index: description: >- 0-based position of the current phase in the build's fixed run order; equals phase_count when done. title: Phase Index type: integer step: anyOf: - type: string - type: 'null' description: >- The span in flight inside a single-step phase, reported by the running step itself. Null when the phase counts its own units, or before the step has reported one. title: Step step_done: anyOf: - type: integer - type: 'null' description: Units of `step` finished, when it has countable units. title: Step Done step_total: anyOf: - type: integer - type: 'null' description: Units `step` has to get through, when that is known. title: Step Total required: - phase_index - phase_count - countable title: KnowledgeGraphBuildProgress type: object AutomaticSearchRouting: additionalProperties: false properties: delegated_wall_ms: anyOf: - type: integer - type: 'null' description: >- Wall time spent preparing and running the native deep or filtered job. title: Delegated Wall Ms fact_wall_ms: anyOf: - type: integer - type: 'null' description: Wall time spent running fact search, when selected. title: Fact Wall Ms final: description: The pipeline that produced the returned output. enum: - fact - agent - deep - filtered title: Final type: string reason: description: The router's explanation of its decision, or the requested `mode`. title: Reason type: string router: description: >- Which router decided, and what it measured: an LLM (its explanation is ``reason``), NaceDM (its probability and decision point), or `requested` when the request's `mode` was `fact` or `agent` and no router ran. Results routed before this field existed read as the LLM. discriminator: mapping: llm: '#/components/schemas/AutomaticLlmRouter' nacedm: '#/components/schemas/AutomaticNaceDmRouter' requested: '#/components/schemas/AutomaticRequestedRouter' propertyName: kind oneOf: - $ref: '#/components/schemas/AutomaticLlmRouter' - $ref: '#/components/schemas/AutomaticNaceDmRouter' - $ref: '#/components/schemas/AutomaticRequestedRouter' title: Router router_model: description: >- The model used to choose the search pipeline; `none` when the request's `mode` named it. title: Router Model type: string router_wall_ms: anyOf: - type: integer - type: 'null' description: Wall time spent selecting the initial route. title: Router Wall Ms selected: description: The route the router chose, or the one the request's `mode` named. enum: - fact - agent - deep - filtered title: Selected type: string required: - selected - final - reason - router_model title: AutomaticSearchRouting type: object DeepSearchV2Result: additionalProperties: false description: >- The result of one source-level deep-search run (``JobKind.DEEP_SEARCH_V2``). Field-for-field the JET shape — answer, reasoning, evidences, the run's ``sql_receipts``, the tool-call trace, session handle, usage, exhaustion — under its own discriminator: the two kinds share one agent chassis and one fold, and a second field list here would only be a place for them to drift. On this surface a receipt's ``rows`` are the statement's bounded preview; the full result is retained server-side and re-queryable through the ``res_…`` handle appearing in any statement that pages it. properties: agent_usage: anyOf: - $ref: '#/components/schemas/JetAgentUsage' - type: 'null' description: >- Root-agent model requests split into execution, compaction, and recovery finalization. Null on the fixed pipeline and on results stored before this telemetry existed; use `usage` for all nested LLM cost. answer: anyOf: - type: string - type: 'null' description: >- The direct, grounded answer to the request. Null only on a run that exhausted its budget before authoring one, or that asked `clarification_questions` instead. title: Answer binding: anyOf: - $ref: '#/components/schemas/LedgerBindingWire' - type: 'null' description: >- The definitional layer the run committed and computed under — which column is the period, which values mean posted, which clock a timing test was verbed on. Null on a run that answered without binding a ledger, which is only possible before any statement ran. cache: anyOf: - $ref: '#/components/schemas/AnswerCacheInfo' - type: 'null' description: >- Set when this answer was re-served from the workspace's answer cache instead of derived by this run, with the provenance of the run that did derive it. Null on every run that computed its own answer. claims: description: >- Calculated answer values, each bound to the execution that produced it. items: $ref: '#/components/schemas/DeepSearchVerifiedClaim' title: Claims type: array clarification: anyOf: - type: string - type: 'null' description: >- The run's clarifying questions as plain text, instead of an answer. Only ever set when the request carried `allow_clarification` and the run needed the user's input to go on; `answer` is null and `evidences` empty alongside it. The same questions, structured, are in `clarification_questions`. title: Clarification clarification_questions: anyOf: - items: $ref: '#/components/schemas/ClarifyingQuestion' maxItems: 2 type: array - type: 'null' description: >- The questions behind `clarification`, at most 2, each with up to 4 suggested answers. Answer them with a follow-up on `session_id` that repeats the query and carries `clarification_answers` (one entry per question, a null answer skips it), or with any follow-up query in your own words. Null on every run that answered. title: Clarification Questions command_receipts: description: Successful shell calculations cited by this answer. items: $ref: '#/components/schemas/CommandReceipt' title: Command Receipts type: array confidence: anyOf: - $ref: '#/components/schemas/ConfidenceLevel' - type: 'null' description: >- The agent's self-graded confidence in the answer — how well the evidence and executed statements support it, on the shared six-level scale (certain / very_high / high / medium / low / speculative). Deep search publishes an answer that cites no evidence, claim or receipt at medium at most, and JE testing publishes a run with any `incomplete` criterion at medium at most. Null on exhausted runs and on results stored before the field existed. coverage: description: >- Complete result tables the answer attached, each with server-rendered rows. items: $ref: '#/components/schemas/DeepSearchCoverage' title: Coverage type: array criteria: description: >- Every requested test and its final disposition, including tests that never reached binding, measurement, or a published figure. Empty only on results stored before this checklist existed. items: $ref: '#/components/schemas/JetCriterionOutcome' title: Criteria type: array degraded: anyOf: - type: string - type: 'null' description: >- Why this result is degraded, when it is. The run broke before it could finalize an answer but had already computed real working, so what is published is that working — `sql_receipts` and `binding` — with `figures` empty and `answer` saying so. Null on every run that finished normally, exhausted ones included. title: Degraded discrepancies: description: >- Where the data contradicted the request's premise or a figure it stated. Empty when nothing did — the run is asked for this explicitly, so an empty list is an answer rather than an omission. items: type: string title: Discrepancies type: array evidences: description: >- The material the answer cites, each resolved to the caller's own uploaded file. items: $ref: '#/components/schemas/SearchEvidence' title: Evidences type: array execution_status: anyOf: - enum: - performed - partially_performed - not_performed type: string - type: 'null' description: >- Whether the run tested what it was asked to test: ``performed`` when every figure was computed, ``partially_performed`` when some criteria could not be, ``not_performed`` when none could. Read it alongside `quality`, which grades how well a performed test went. JE-testing always sets this on a finished run; other JetResult subclasses (deep search) leave it null, as do results stored before the field existed. title: Execution Status exhausted: default: false description: >- Step budget hit before the run was satisfied. A successful response, not a failure. title: Exhausted type: boolean figures: description: >- One entry per criterion tested, each linked to the receipts its figures are readable out of. Empty on a run that answered without testing anything, or that exhausted its budget first. items: $ref: '#/components/schemas/JetFigure' title: Figures type: array grounding_job_ids: anyOf: - items: format: uuid type: string type: array - type: 'null' description: >- Ground jobs planned for this search's evidences. Empty when postprocessing is disabled or no evidence is groundable. Absent on results stored before the field existed, so a client can still POST /v1/ground for those jobs. title: Grounding Job Ids population_statement: anyOf: - type: string - type: 'null' description: >- The population every figure was computed over — file, period, layer, status, basis, grain — in the run's own words. Null only on a run that never authored an answer. title: Population Statement quality: anyOf: - $ref: '#/components/schemas/JetQuality' - type: 'null' description: >- Structured execution quality: clean vs recovered-with-warnings vs degraded, plus the fail-open checks, tool-failure counts, and missing audit artifacts that produced that status. JE-testing always sets this on a finished run. Other JetResult subclasses (deep search) leave it null. Null also on results stored before the field existed. reasoning: anyOf: - type: string - type: 'null' description: How the receipted statements chain together into the answer. title: Reasoning result_type: const: deep_search_v2 default: deep_search_v2 title: Result Type type: string session_id: anyOf: - format: uuid type: string - type: 'null' description: >- The conversation this run belongs to. Send it back as the request's `session_id` to ask a follow-up in the same thread. title: Session Id spec_digest: anyOf: - type: string - type: 'null' description: >- A short fingerprint of what this run committed to TEST — the rows, grain, clock, encoding, thresholds and time window each criterion was pinned to — with the free-text justifications beside those choices excluded. Two runs of the same question carry the same value when they tested the same thing, so an unstable answer can be told apart from an answer to a quietly different question without re-reading either run. Null on a run that committed no test spec, and on other JetResult subclasses. title: Spec Digest sql_receipts: description: >- Every statement the run executed, in execution order — the answer's working. items: $ref: '#/components/schemas/SqlReceipt' title: Sql Receipts type: array steps_used: default: 0 description: >- Legacy procedure-step count retained for compatibility. It is engine-specific and is not a model-request count; agent runs expose completed root-model requests in `agent_usage`. Read it with `exhausted`, which says whether the configured request budget ran out before the run was satisfied. title: Steps Used type: integer structured_answer: anyOf: - $ref: '#/components/schemas/JsonValue' - type: 'null' description: >- `answer` parsed as JSON, set only when the request carried `output_schema` and the answer validates against it; a field the source does not state is null whatever type the schema gives it. Null on every run without a schema, and on a run whose answer still missed the schema after its corrections, where `answer` holds the text as written. tool_calls: description: >- One entry per tool the run invoked, in execution order — the tool's name, a digest of its arguments, how many results came back, and how long it took. The run's shape, not its content. items: $ref: '#/components/schemas/ToolCallTrace' title: Tool Calls type: array usage: anyOf: - $ref: '#/components/schemas/SearchLlmUsage' - type: 'null' description: >- What this run spent on LLM calls. Present only when the request asked for it; null means nothing was measured, not that nothing was spent. title: DeepSearchV2Result type: object FilteredSearchResult: additionalProperties: false description: >- The typed outcome of one filtered-search execution (or one page of it). ``exhaustive`` is the coarse completeness signal: when it is false, returned matches are valid, but "all"-style claims, ``total_matches`` as a census, and zero-match conclusions are not guaranteed. It is scope-wide and all-or-nothing, so it cannot say *what* was incomplete; ``field_readability`` is its per-field companion, naming the filtered fields the extraction could not fully read — the difference between "no component matched" and "the column you filtered on was largely unreadable". Pagination is LIVE — each page re-executes against the current catalog, so concurrent ingestion, deletion, or relabeling may shift later pages (rows can repeat or be skipped across page boundaries); ``catalog_drifted`` says the scope changed since the query was first validated. properties: applied_query: anyOf: - type: string - type: 'null' description: Server-rendered display form of the published query. title: Applied Query candidates_seen: default: 0 title: Candidates Seen type: integer catalog_drifted: default: false description: The catalog changed since the query was validated. title: Catalog Drifted type: boolean clarification: anyOf: - type: string - type: 'null' description: >- Non-null exactly when the run asked a clarifying question instead of executing — only possible when the initial query set `allow_clarification`: no rows, no applied_query, exhaustive false. Filtered search keeps no session; answer it by issuing a new initial query. title: Clarification columns: items: $ref: '#/components/schemas/CatalogColumnDescriptor' title: Columns type: array confidence: anyOf: - $ref: '#/components/schemas/ConfidenceLevel' - type: 'null' description: >- The agent's self-graded confidence in the published result — how well the catalog evidence supports its reading of the request, on the shared six-level scale (certain / very_high / high / medium / low / speculative). Null on runs rejected with a `clarification`, on page requests, and on results stored before the field existed. content_evidences: description: >- Residual content condition passages, server-verified; present only on residual queries. items: $ref: '#/components/schemas/ContentEvidence' title: Content Evidences type: array content_verification: anyOf: - $ref: '#/components/schemas/ContentVerificationSummary' - type: 'null' description: >- Coverage of the content criterion check. Null for pure catalog queries and older results. An empty result with unverified candidates does not establish that no documents match. coverage: $ref: '#/components/schemas/Coverage' evidences: description: >- Referent-resolution evidence: the file passages that turned a role or relative referent in the query ('the CEO') into the concrete filter value the published query uses. Agent-cited, then resolved server-side to the caller's own uploaded file exactly like search evidence — an entry that cannot be resolved to a visible file is dropped, never published. Distinct from content_evidences, which are server-verified residual matches. Empty on pure catalog queries. items: $ref: '#/components/schemas/SearchEvidence' title: Evidences type: array executed_at: anyOf: - format: date-time type: string - type: 'null' description: When this page's snapshot was read. title: Executed At exhausted: default: false description: Step budget hit before the agent finished. A success, not a failure. title: Exhausted type: boolean exhaustive: default: false description: >- True only when every eligible component was completely cataloged and evaluated — the scope-wide completeness signal. False whenever coverage is partial or a residual content condition was applied. title: Exhaustive type: boolean field_readability: description: >- Filtered fields the extraction could not fully read, server-computed. An empty list is an answer — every field the query filtered on was fully readable — rather than an omission. items: $ref: '#/components/schemas/FieldReadability' title: Field Readability type: array next_cursor: anyOf: - type: string - type: 'null' description: >- Opaque cursor for the next page — POST it back as {type: 'page', cursor}. Null on the last page. title: Next Cursor result_type: const: filtered_search default: filtered_search title: Result Type type: string result_unit: default: component description: >- The unit used for rows, totals, top-N and pagination. New searches consistently return catalog entries with their established identities. Legacy units remain readable. enum: - source - component - entity - entry title: Result Unit type: string rows: items: $ref: '#/components/schemas/FilteredSearchRow' title: Rows type: array steps_used: default: 0 title: Steps Used type: integer tool_calls: items: $ref: '#/components/schemas/ToolCallTrace' title: Tool Calls type: array total_files: anyOf: - type: integer - type: 'null' description: >- Distinct source files supporting the confirmed matches before any page or top-N cut. Null for older results or when no authoritative selection was executed. Subject to the same completeness as total_matches. title: Total Files total_matches: default: 0 description: Confirmed matches in result_unit, before any page or top-N cut. title: Total Matches type: integer truncated: default: false description: A structural cap degraded this result; matches shown remain valid. title: Truncated type: boolean title: FilteredSearchResult type: object UsageLine: additionalProperties: false description: One part of a job's final credits. properties: credits: description: >- quantity x credits_per_unit x multiplier: what this part added to the job's credits. 0 when waived. minimum: 0 title: Credits type: integer credits_per_unit: description: The credit schedule's rate for one unit of this part. minimum: 0 title: Credits Per Unit type: integer multiplier: description: 2 on the parse part of a parse_mode "high" job, otherwise 1. minimum: 1 title: Multiplier type: integer part: description: >- parse: reading the document into text. operation: the tool's own work on what was parsed. enum: - parse - operation title: Part type: string quantity: description: How many units this part was charged for. minimum: 0 title: Quantity type: integer unit: description: >- What quantity counts: page is a page or page-equivalent (a spreadsheet's non-empty cells, a minute of audio), item is a ground item, unit is a job priced by its units directly (agent steps). enum: - page - item - unit title: Unit type: string waiver: anyOf: - $ref: '#/components/schemas/UsageWaiver' - type: 'null' description: Which work was not charged and why. Null when charged. required: - part - quantity - unit - credits_per_unit - multiplier - credits title: UsageLine type: object AutomaticLlmRouter: additionalProperties: false description: An LLM chose the route. Its explanation is the routing's ``reason``. properties: kind: const: llm default: llm title: Kind type: string title: AutomaticLlmRouter type: object AutomaticNaceDmRouter: additionalProperties: false description: >- NaceDM, the decision model, chose the route by scoring how likely the query needs the agent. properties: decision_point: description: >- The agent runs when ``p_agent`` is at or above this; fact search runs below it. maximum: 1 minimum: 0 title: Decision Point type: number kind: const: nacedm default: nacedm title: Kind type: string p_agent: anyOf: - maximum: 1 minimum: 0 type: number - type: 'null' description: >- NaceDM's probability that the query needs the investigating agent rather than one fact-search pass; 1 - p_agent is the probability that fact search settles it. Null when the request was too long for NaceDM to score, which routes to the agent. title: P Agent required: - p_agent - decision_point title: AutomaticNaceDmRouter type: object AutomaticRequestedRouter: additionalProperties: false description: 'No router ran: the request''s ``mode`` named the route.' properties: kind: const: requested default: requested title: Kind type: string title: AutomaticRequestedRouter type: object JetAgentUsage: additionalProperties: false description: >- Completed root-agent model requests by session phase. This is intentionally separate from :class:`SearchLlmUsage`: that ledger covers every nested LLM call and token, while this block explains the agent procedure itself. Provider transport attempts are not exposed by the model boundary reliably and are therefore not guessed here. properties: compaction_requests: description: Completed model requests used to summarize compacted history. minimum: 0 title: Compaction Requests type: integer execution_requests: description: Completed model requests in normal execution cycles. minimum: 0 title: Execution Requests type: integer finalization_requests: description: Completed requests in the tool-less recovery finalizer. minimum: 0 title: Finalization Requests type: integer total_requests: description: Sum of execution, compaction, and finalization requests. minimum: 0 title: Total Requests type: integer required: - execution_requests - compaction_requests - finalization_requests - total_requests title: JetAgentUsage type: object LedgerBindingWire: additionalProperties: false description: >- The definitional layer a run committed, echoed for the caller to read. This is the answer to "on what definitions does this figure rest" — the question the prose relay of the old playbook could not answer, and the reason the binding is a validated artifact rather than a paragraph. Every pin was checked against the tables' own profiles before the run was allowed to compute anything: the columns exist with compatible types, the period roles partition the observed domain, each clock's declared grain matches its column, and every encoding value occurs in its column. Published as flat slot listings rather than as a mirror of the internal model's tree. Two reasons, both practical: a reader wants "which column is the approval clock" answered in one place rather than by walking a nested object, and a slot the design adds later becomes another row here instead of a change to this contract. properties: columns: description: Every column pinned to a slot, in slot order. items: $ref: '#/components/schemas/BoundColumn' title: Columns type: array notes: description: Deviations the run observed while orienting. items: type: string title: Notes type: array periods: description: The period domain, in period order, with roles. items: $ref: '#/components/schemas/BoundPeriod' title: Periods type: array policy_sheets: description: >- Documents the run treated as settling parameters (a sequence policy, a topside register). items: type: string title: Policy Sheets type: array revised_because: anyOf: - type: string - type: 'null' description: >- Why the binding was replaced mid-run, when it was. Null on a run that bound once. title: Revised Because tables: items: $ref: '#/components/schemas/BoundTable' title: Tables type: array value_sets: description: >- Encoding candidates and layer memberships. More than one entry under 'encodings.manual' means the run kept both readings and resolved them per test. items: $ref: '#/components/schemas/BoundValueSet' title: Value Sets type: array title: LedgerBindingWire type: object AnswerCacheInfo: additionalProperties: false description: >- How a search answer relates to the workspace's semantic answer cache. Present only on a run that served a previously derived answer instead of deriving a new one. Everything else on the result — the evidences, the reasoning, the tool-call trace, the receipts — describes that ORIGINAL derivation, which is what this block exists to say out loud: the answer was computed once, for a question near enough to this one, under an identical scope and an identical access gate, and re-checked against the workspace before it was handed back. A result with no ``cache`` block was derived by the run that returned it. properties: cached_at: description: >- When the answer was originally derived. Read it as the age of the evidence: the workspace may have changed since, which is what the re-check below is for. format: date-time title: Cached At type: string served_from_cache: description: >- True when this result was re-served from a previously derived answer rather than computed by this run. Always true where this block appears at all. title: Served From Cache type: boolean source_job_id: anyOf: - format: uuid type: string - type: 'null' description: >- The job whose run originally derived this answer. Null when that job's row has since been reaped — the answer outlives the record of the run that produced it. title: Source Job Id verified_at: description: >- When this run re-checked the cached answer's citations against the workspace and accepted them. Always this run's own time — a cached answer is never served unchecked. format: date-time title: Verified At type: string required: - served_from_cache - cached_at - verified_at title: AnswerCacheInfo type: object DeepSearchVerifiedClaim: additionalProperties: false description: One calculated answer value, bound to the execution that produced it. properties: answer_excerpt: anyOf: - type: string - type: 'null' description: Exact displayed answer value selected for its calculation citation. title: Answer Excerpt answer_occurrence: default: 0 description: Zero-based occurrence of answer_excerpt in the answer. minimum: 0 title: Answer Occurrence type: integer claim: description: >- The method or formula behind the calculated value, as the agent wrote it. title: Claim type: string claim_id: description: Unique id of this calculation within the result. title: Claim Id type: string evidence_indices: description: Source evidence indices supporting the calculation inputs. items: type: integer title: Evidence Indices type: array reference: $ref: '#/components/schemas/DeepSearchClaimReference' description: Exact address of the supporting result value. required: - claim_id - claim - reference title: DeepSearchVerifiedClaim type: object ClarifyingQuestion: additionalProperties: false description: One question a run asked back instead of answering. properties: options: description: >- Suggested answers, most likely first. Never exhaustive: the user may always answer in their own words, so no option stands for 'Other'. Empty when the run offered none. items: type: string title: Options type: array question: description: The question, as the run asked it. title: Question type: string required: - question title: ClarifyingQuestion type: object CommandReceipt: additionalProperties: false properties: command: description: The shell command as executed. title: Command type: string outputs: additionalProperties: type: string description: >- Named scalar outputs parsed from stdout; a scalar output is named value. title: Outputs type: object result_id: description: Job-scoped identity of a recorded shell execution. title: Result Id type: string stdout: description: The complete standard output of the successful command. title: Stdout type: string required: - result_id - command - stdout - outputs title: CommandReceipt type: object ConfidenceLevel: description: How well the retrieved evidence supports the answer, worst-case wins. enum: - certain - very_high - high - medium - low - speculative title: ConfidenceLevel type: string DeepSearchCoverage: additionalProperties: false description: >- How one requested deliverable was answered, partially answered, or refused. properties: absence_result_ids: description: Zero-row receipts proving those inputs absent. items: type: string title: Absence Result Ids type: array basis: default: sql description: >- Whether support is retained SQL or document retrieval; document absence is not a SQL-verified proof. enum: - sql - document - calculation title: Basis type: string claim_ids: description: Verified claims satisfying this output. items: type: string title: Claim Ids type: array complete_result: anyOf: - $ref: '#/components/schemas/JetBreakdown' - type: 'null' description: >- Server-rendered rows from the retained listing, never copied from model prose. complete_result_id: anyOf: - type: string - type: 'null' description: >- Receipt containing the requested complete listing; page it when its attached breakdown is truncated. title: Complete Result Id deliverable_id: description: Unique id for one requested output. title: Deliverable Id type: string description: description: Requested output this item accounts for. title: Description type: string evidence_indices: description: >- Zero-based indices into this result's published evidences supporting a document deliverable. items: type: integer title: Evidence Indices type: array missing_inputs: description: Inputs preventing a complete answer. items: type: string title: Missing Inputs type: array status: description: Whether the output was fully answerable. enum: - answered - partial - unanswerable title: Status type: string required: - deliverable_id - description - status title: DeepSearchCoverage type: object JetCriterionOutcome: additionalProperties: false description: The final disposition of one requested test. properties: blocker: anyOf: - enum: - binding_unresolved - measurement_failed - missing_finding - population_incomplete - context_exhausted - missing_business_parameter - methodology_unresolved - finding_unverified type: string - type: 'null' description: >- Why an incomplete test did not finish, including reasons newer than the three `incomplete_reason` keeps to. Null for performed and cannot-be-performed tests. title: Blocker criterion_id: description: >- Stable short id for this requested test. Its TestSpec and published figure use the same id. minLength: 1 title: Criterion Id type: string description: description: >- The requested test in the caller's terms, without an invented conclusion. minLength: 1 title: Description type: string incomplete_reason: anyOf: - enum: - binding_unresolved - measurement_failed - missing_finding type: string - type: 'null' description: >- `blocker` in the three values older SDKs accept: `population_incomplete` and `finding_unverified` read as `measurement_failed`, and every other newer blocker as `missing_finding`. Read `blocker` for the full reason. title: Incomplete Reason missing_parameters: description: >- Policy inputs this test was missing. Set only when `blocker` is `missing_business_parameter` or `methodology_unresolved`; empty otherwise. items: enum: - close_cutoff - balance_tolerance - selected_user - authority_limit - methodology - required_fields type: string title: Missing Parameters type: array spec_id: anyOf: - type: string - type: 'null' description: >- The committed TestSpec id and matching `figures[].spec_id`. Null when setup never reached a spec. title: Spec Id status: description: >- Whether the test produced a finding, proved it could not be performed, or remained incomplete. enum: - performed - cannot_be_performed - incomplete title: Status type: string required: - criterion_id - description - status title: JetCriterionOutcome type: object SearchEvidence: additionalProperties: false description: >- One piece of evidence the search agent cited, named as the caller's own file. The agent retrieves from workspace-internal ingestion derivatives, but those are an implementation detail the caller never addresses: every citation is resolved server-side, through the caller's access gate, to the uploaded file it belongs to (``source_path`` + ``source_file_id``). A citation that cannot be resolved to a visible file — hallucinated, deleted mid-run, or access-refused — is dropped rather than published under a path the caller cannot use. No locator: pinning a quote to a region of the original document is a separate ``ground`` call the caller makes on the file at ``source_path`` (``source_file_id``) with ``quote`` as the target text — and, for a quote taken from a spreadsheet, ``component`` as the target's ``sheet``. properties: component: anyOf: - type: string - type: 'null' description: >- Public component of the file the quote came from — the tab name for a spreadsheet, the section for a split document; the same vocabulary file-metadata lists. Pass it as the ground target's sheet when grounding a spreadsheet quote. None for a single-component file or when attribution was unavailable. title: Component derivation: anyOf: - $ref: '#/components/schemas/DerivationTrace' - type: 'null' description: >- Computation DAG for derived answers; None when the evidence is a direct extraction or the run recorded no dependency edges. page: anyOf: - type: integer - type: 'null' description: 1-based page number, when the agent saw one. title: Page queries: description: >- The SQL the run executed over this evidence's table, with a bounded preview of each result — server-recorded from the run's tables engine, never model-authored. Attached whenever the run queried the cited table (or the row extraction of the same spreadsheet tab), so a verbatim quote from a queried sheet carries the computation trail alongside it; empty when the run never queried the cited file's tables. items: $ref: '#/components/schemas/TableQueryGrounding' title: Queries type: array quote: description: The key passage, as retrieved from the file. title: Quote type: string relevance: default: '' description: >- Deprecated: empty on new results, where `reasoning` says how the evidences support the answer. title: Relevance type: string source_file_id: anyOf: - format: uuid type: string - type: 'null' description: >- The id of the file at source_path, resolved server-side. Always set on newly finalized results; null only on results stored before unresolvable citations were dropped. title: Source File Id source_path: description: >- The uploaded file the quote belongs to, e.g. 'reports/policy.pdf'. This is the file to ground the quote against. title: Source Path type: string required: - source_path - quote title: SearchEvidence type: object JetFigure: additionalProperties: false description: >- One criterion the run tested, and the statements its figures come from. The answer's structure on the wire. ``JetResult.answer`` is prose a person reads; this is the same content a reviewer can *check*: the definition the figure was computed under, the population it was computed over, the spec that pinned both, and the ``sql_receipts`` entries the figures are readable out of. Every ``result_id`` here names a receipt on the same result, so a reader follows a figure to its statement and its rows without leaving the payload. ``exception_listing_result_id`` is the one worth opening: an unfiltered count grounds correctly but points at every row, while an exception listing points at the rows that failed. properties: band_group: anyOf: - type: string - type: 'null' description: >- Set when this figure is one band of a family that partitions a population — the same name on every band of the family, whose counts sum to that population. title: Band Group breakdown: anyOf: - $ref: '#/components/schemas/JetBreakdown' - type: 'null' description: >- The tabular result behind this figure, attached by the server from the receipt it cites — the exception listing where there is one, otherwise the single cited statement that returned more than one row. Null when no cited statement holds a table, and on a criterion that could not be performed. cannot_be_performed: default: false description: >- The workspace does not hold the material this criterion needs. `result_ids` then name the probes that establish the absence rather than the figures. title: Cannot Be Performed type: boolean count: description: Members of the population that met the criterion. minimum: 0 title: Count type: integer criterion: description: What was tested, in the caller's terms. title: Criterion type: string definition: description: >- The definition it was tested under: which column and values encoded the term, which clock, which basis, which threshold and where it came from. title: Definition type: string exception_listing_result_id: anyOf: - type: string - type: 'null' description: >- The receipt that lists the exceptions themselves, when one was produced. title: Exception Listing Result Id population: description: >- The denominator — rows at this test's grain that the criterion ran over. minimum: 0 title: Population type: integer result_ids: description: >- `sql_receipts[].result_id` of every statement this figure is readable out of. items: type: string title: Result Ids type: array spec_id: description: The run's committed TestSpec this figure was computed under. title: Spec Id type: string value: anyOf: - type: string - type: 'null' description: >- The exceptions' value as text, so a decimal survives the wire. Null for a count-only criterion. title: Value required: - criterion - definition - spec_id - population - count title: JetFigure type: object JetQuality: additionalProperties: false description: >- Structured execution-quality reporting for one JE-testing result. Distinguishes a clean, fully evidenced success from a recovered or partially validated one without changing ``ok`` or inventing figures. Contains only check names, tool names, outcome categories, and counts — never prompts, answers, evidence bodies, shell output, or client identifiers. properties: missing_artifacts: description: >- Required audit artifact classes absent from a quantitative result (``binding`` and/or ``sql_receipts``). Empty when every finding is ``cannot_be_performed`` or when both artifacts are present. items: enum: - binding - sql_receipts type: string title: Missing Artifacts type: array retried_checks: description: >- Output-contract check families that cost the answer a model re-emission, whether or not the re-emission repaired them. Attribution only — a retry the model then satisfied is a clean answer, so this does not move ``status``. items: enum: - specs - scope - cycle - grain - basis - absence - bands - pointer - delivery - figures type: string title: Retried Checks type: array status: description: >- ``clean`` when nothing was recovered; ``recovered_with_warnings`` when a fail-open check, tool failure, or missing audit artifact was recorded; ``degraded`` when the run salvaged working after a hard failure (see ``JetResult.degraded``). enum: - clean - recovered_with_warnings - degraded title: Status type: string tool_failures: description: >- Non-success tool outcomes the agent recovered from, aggregated by tool and category. items: $ref: '#/components/schemas/JetToolFailure' title: Tool Failures type: array validation_warnings: description: >- Fail-open output checks that passed the answer through after their corrective retry. items: $ref: '#/components/schemas/JetValidationWarning' title: Validation Warnings type: array withheld_receipt_figures: default: 0 description: >- How many performed figures were published with no readable receipt id — either the statements behind them are not visible to this caller, or the figure was computed without one. The figures themselves are still returned; this counts the ones whose working cannot be inspected. minimum: 0 title: Withheld Receipt Figures type: integer required: - status title: JetQuality type: object SqlReceipt: additionalProperties: false description: >- One SQL statement a journal-entry-testing run executed, with its result. The audit trail of a JET answer: every headline figure is meant to be readable out of one of these. Unlike :class:`TableQueryGrounding` — whose SQL is written by a sub-agent and published as supporting detail — the statement here is the deliverable's own working, so it is published whole rather than digested. ``rows`` is bounded (``JET_RECEIPT_MAX_ROWS``) and ``truncated`` says whether the bound cut anything, so an "every exception is listed" reading is never made from a silently capped table. ``result_row_count`` is the figure that reading actually needs: the statement's whole result is stored, and this is its size, whatever the bound carried below. properties: columns: description: Result column names, in result order. items: type: string title: Columns type: array executor: anyOf: - type: string - type: 'null' description: >- The named executor that generated this statement (`reconcile_movement`, `test_timing`, `find_duplicates`, `field_completeness`, `journal_balance`), when one did, `custom_sql` for a statement the fixed-pipeline engine authored under its escape, or `ledger_understanding` for the ledger-understanding census's own statement, which ran before this run and is cited rather than re-run. Null when no named generator produced it — a population count, an absence probe, or SQL the agent wrote itself. Both engines use the same words here. title: Executor grounding_status: anyOf: - enum: - exact - unavailable - zero_result type: string - type: 'null' description: >- Whether this statement's stored result already carried proof of which source rows it read when the receipt was recorded. 'exact' means it did; 'unavailable' means the proof could not be read; 'zero_result' means there were no rows to ground. Null when nothing had been captured yet — the ordinary case for a lane that captures at publication time, so this is a record of what execution happened to know and NOT a prediction of whether the receipt can be grounded. What was actually proven is published as `grounding_status` on the matching evidence query, beside the `regions` it earned. title: Grounding Status handle: anyOf: - type: string - type: 'null' description: >- Content-addressed key of this statement's stored result, derived from the statement text. Server-side identity: it is what lets the run's own publication find the stored result and its capture-time provenance, and it is NOT an address an agent may query or chain from — `result_id` is the identity the caller and the row pager use. Null on a run that stored no result for the statement. A `cat_` handle names an exploratory document-catalog query: it stores no result beyond the rows carried here. title: Handle parameters: additionalProperties: type: string description: >- The executor's resolved call, flattened to text — the clock and its true grain, the window's day offsets, the signature, the tolerance, the population. Empty on a statement no executor generated. This is what makes a figure trace to a named, parameterized computation rather than to SQL alone. title: Parameters type: object replay: anyOf: - $ref: '#/components/schemas/SqlReplayReceipt' - type: 'null' description: >- Independent recomputation metadata for this statement; null on legacy results. result_id: description: >- Stable per-run identity of this statement, in execution order (e.g. 'sql_3'). title: Result Id type: string result_row_count: default: 0 description: >- Rows in the statement's complete stored result. Equal to `row_count` when nothing was cut; the number a total or an exception count must be read from when `truncated` is set. title: Result Row Count type: integer row_count: default: 0 description: Rows carried below — not the statement's unbounded result size. title: Row Count type: integer rows: description: >- Result rows, values rendered as text so a decimal, a date and a NULL all survive the wire. items: additionalProperties: type: string type: object title: Rows type: array saved_as: anyOf: - type: string - type: 'null' description: >- The session view this statement was registered as, when it was. Every name in another receipt's ``views_used`` appears here on exactly one receipt, so the run's receipts define every view they cite. title: Saved As sql: description: The statement as executed, verbatim. title: Sql type: string table_bindings: description: >- The tables this statement registered, each with the view name it was referenced by. items: $ref: '#/components/schemas/SqlTableBinding' title: Table Bindings type: array truncated: default: false description: Whether rows past the stored cap were cut from this receipt. title: Truncated type: boolean view_sql: anyOf: - type: string - type: 'null' description: >- The definition registered under `saved_as`, when it is not this statement itself. Null on an ordinary `save_as`, where `sql` IS the definition. Set by `build_journal_view`, which registers the per-journal frame and runs a bounded probe over it rather than materializing the whole frame — so the definition every later `views_used` refers to is still published by exactly one receipt. title: View Sql views_used: description: >- Session views registered when this statement ran, in definition order — the registry snapshot it executed under. A statement naming a view is replayable only against these, which is what makes named views admissible where chaining a previous call's result handle is not. items: type: string title: Views Used type: array warnings: description: >- Pre-execution lint notes attached to this statement — non-blocking, and published as part of its working. items: type: string title: Warnings type: array required: - result_id - sql title: SqlReceipt type: object ToolCallTrace: additionalProperties: false description: >- Carries an argument digest rather than raw arguments. Raw arguments would be a side channel around ``Coverage``: a caller could read back what the loop searched for on its behalf. properties: arguments_digest: title: Arguments Digest type: string duration_ms: title: Duration Ms type: integer hits: title: Hits type: integer tool: title: Tool type: string required: - tool - arguments_digest - hits - duration_ms title: ToolCallTrace type: object SearchLlmUsage: additionalProperties: false description: >- What answering one search query cost in LLM work. Present only when the run was asked to account for itself *and* spend reached its ledger; ``null`` otherwise, so a caller can tell "nothing was measured" from "nothing was spent". An empty ledger publishes ``null`` rather than a zeroed object for that reason: zeros would claim a measured run cost nothing, when what an empty ledger most likely records is accounting that never landed. The totals cover recorded model calls at any depth: the agent's own turns, and the calls the retrieval tools made on its behalf — a document read by the recursive-LLM engine, a scan cracked by the vision engine, a tables question answered by the SQL agent. That is the number a per-query cost figure needs, and it is invariably several times the agent's own turn count. ``by_model`` is the same spend split by the model that served it, because a run legitimately spends on several at different prices — a total alone cannot be turned into money. The totals are the sum of ``by_model`` and are published anyway so the common case needs no arithmetic. Observed retries are included. These public token totals are not a complete cost certificate: provider omissions and failed persistence can leave gaps. Internal coverage and non-token counters stay in the ledger and are not added to this wire shape without a separate SDK contract update. properties: by_model: description: The same spend per model that served it, highest first. items: $ref: '#/components/schemas/ModelTokenUsage' title: By Model type: array cached_input_tokens: default: 0 description: >- The share of input_tokens served from a provider prompt cache — billed at a reduced rate, so it is reported separately rather than subtracted. title: Cached Input Tokens type: integer input_tokens: default: 0 description: Prompt tokens across every request, cached ones included. title: Input Tokens type: integer output_tokens: default: 0 description: Completion tokens across every request. title: Output Tokens type: integer requests: default: 0 description: Completed LLM requests, tool-internal ones included. title: Requests type: integer title: SearchLlmUsage type: object CatalogColumnDescriptor: additionalProperties: false description: One extracted field the result's rows may carry. properties: description: default: '' title: Description type: string field: title: Field type: string filtered: default: false description: >- The published query filtered on this column — or ranked by it under a top-N LIMIT, where ranking decides membership (server-extracted from the SQL, never model-authored). These are the values the matches hinge on, and the first cells worth grounding against their source documents. title: Filtered type: boolean kind: enum: - text - date - money - number - boolean title: Kind type: string repeated: default: false description: Several values may exist per row (parties, signatories). title: Repeated type: boolean requested: default: false description: >- The user requested this output field; missing values do not exclude a match. title: Requested type: boolean required: - field - kind title: CatalogColumnDescriptor type: object ContentEvidence: additionalProperties: false description: >- One passage that satisfied the residual content condition, server-verified. properties: a1_range: anyOf: - type: string - type: 'null' description: >- The exact native cell or range containing this quotation, within component. title: A1 Range component: anyOf: - type: string - type: 'null' title: Component page: anyOf: - type: integer - type: 'null' title: Page quote: title: Quote type: string source_file_id: format: uuid title: Source File Id type: string source_path: title: Source Path type: string required: - source_path - source_file_id - quote title: ContentEvidence type: object ContentVerificationSummary: additionalProperties: false description: Coverage of the bounded content check, separate from catalog coverage. properties: candidates: description: Catalog candidates considered by the cited content check. minimum: 0 title: Candidates type: integer condition: description: The content condition checked on catalog-selected candidates. title: Condition type: string unverified_candidates: description: >- Candidates whose condition could neither be established nor ruled out, including bounds or unavailable evidence. These records are excluded from confirmed matches, not treated as non-matches. minimum: 0 title: Unverified Candidates type: integer required: - condition - candidates - unverified_candidates title: ContentVerificationSummary type: object Coverage: additionalProperties: false description: >- What the access gate withheld, in counts and label names only. Never a name, path, or fragment of withheld content. Naming the labels leaks nothing the caller cannot already read from the workspace config, and it turns "some results were withheld" into an actionable request. properties: labels_required: description: Which labels would have been needed to see the withheld candidates. items: type: string title: Labels Required type: array request_access_hint: anyOf: - type: string - type: 'null' title: Request Access Hint restricted_candidates: default: 0 title: Restricted Candidates type: integer title: Coverage type: object FieldReadability: additionalProperties: false description: >- How much of one filtered field the extraction could actually read. Only a ``found`` observation materializes a value, so a comparison against a field the extraction did not resolve silently drops those components: the query is correct and the result is empty for a reason that has nothing to do with the caller's question. Reported per field the query filtered on, and only when ``readable < in_scope`` — a fully readable field says nothing. Read it with ``total_matches``: when ``readable`` is 0 the empty result carries no information about the population, and when the unreadable remainder is large next to ``total_matches`` the matches shown are a floor, not a census. properties: field: description: The extracted field the query filtered on. title: Field type: string in_scope: description: Components in scope whose document type carries this field. title: In Scope type: integer readable: description: >- Of those, how many had a resolved value the predicate could evaluate. title: Readable type: integer required: - field - in_scope - readable title: FieldReadability type: object FilteredSearchRow: additionalProperties: false description: One catalog entry, or a historical result, with its supporting evidence. properties: category: anyOf: - type: string - type: 'null' description: The component's primary taxonomy category. title: Category cells: description: Typed observations belonging to this component. items: $ref: '#/components/schemas/FilteredSearchCell' title: Cells type: array component: description: >- Public component name — the tab or document section, matching the component= argument of the file tools (qa-file, read-file, query-tables). Several document rows can share one section name; page_start/page_end distinguish them. A media row's name is the recording stem, display-only (file tools take the whole file). title: Component type: string component_kind: description: The representation containing these observations. enum: - document - sheet - media title: Component Kind type: string components: description: >- Supporting records grouped into this result, in query order, with their separate values and evidence. The row's component fields mirror the first record for display. Empty when no grouping was needed or on older results. items: $ref: '#/components/schemas/FilteredSearchComponent' title: Components type: array content_matches: description: >- Content criteria this row satisfied, with observed values and the source passages used to verify them. items: $ref: '#/components/schemas/ContentConditionMatch' title: Content Matches type: array document_type: anyOf: - type: string - type: 'null' description: The profiled document type of this component. title: Document Type entity_id: anyOf: - type: string - type: 'null' description: The printed identifier of the matching entity within a register. title: Entity Id entry_id: anyOf: - format: uuid type: string - type: 'null' description: >- Catalog entry identity, independent of query wording, filtering and rank. Supporting profile records share an established structural identity; incomplete identities can change on catalog rebuild. Null on legacy units. title: Entry Id page_end: anyOf: - type: integer - type: 'null' description: Last source page containing the component. title: Page End page_start: anyOf: - type: integer - type: 'null' description: First source page containing the component. title: Page Start source_file_id: description: Stable identity of the uploaded source file. format: uuid title: Source File Id type: string source_path: description: The uploaded file the result belongs to. title: Source Path type: string source_row: anyOf: - type: integer - type: 'null' description: The native sheet row containing this entity's facts. title: Source Row subcategory: anyOf: - type: string - type: 'null' description: The component's primary taxonomy subcategory. title: Subcategory summary: default: '' description: A description of the component's contents. title: Summary type: string required: - component - component_kind - source_path - source_file_id title: FilteredSearchRow type: object UsageWaiver: additionalProperties: false description: Why part of a job, or the whole job, was not charged. properties: part: description: >- parse: the parse part was not charged. job: nothing in the job was charged. enum: - parse - job title: Part type: string reason: description: >- reused_parse: the job read a parse your earlier job already paid for. repeat_of_job: the job repeated your earlier job exactly and was answered with its result. enum: - reused_parse - repeat_of_job title: Reason type: string source_job_id: anyOf: - format: uuid type: string - type: 'null' description: >- Always null: billing history must not disclose another job as its visibility changes. title: Source Job Id required: - part - reason title: UsageWaiver type: object BoundColumn: additionalProperties: false description: One column the run pinned to a definitional slot. properties: column: title: Column type: string component: anyOf: - type: string - type: 'null' title: Component detail: anyOf: - type: string - type: 'null' description: >- What the slot additionally states about this column — a clock's true grain, that a basis is the one the trial balance ties to, what a calendar date means. title: Detail path: title: Path type: string slot: description: >- The slot this column fills, dotted: 'journal_key', 'clocks.created', 'amount_bases[reporting].debit', 'accounts.fsli'. title: Slot type: string table_name: title: Table Name type: string required: - slot - path - table_name - column title: BoundColumn type: object BoundPeriod: additionalProperties: false description: >- One value of the period axis and the role the run gave it, in period order. properties: role: description: '''opening'', ''month'', ''year_end_adj'' or ''total_row''.' title: Role type: string value: title: Value type: string required: - value - role title: BoundPeriod type: object BoundTable: additionalProperties: false description: One table of the package, and the role the run bound it to. properties: component: anyOf: - type: string - type: 'null' description: The tab, when the file contributed more than one table. title: Component path: description: The uploaded file, e.g. 'ledger/journal.xlsx'. title: Path type: string role: description: >- The slot it fills: 'journal_lines', 'journal_headers', 'trial_balance', …. title: Role type: string table_name: description: The view name this run's SQL referenced it by. title: Table Name type: string required: - role - path - table_name title: BoundTable type: object BoundValueSet: additionalProperties: false description: >- One column-and-values pin: an encoding candidate, or a layer's membership. Named even when its slot carries only one, because the name is what a test cites when a slot carries two — which is a state this binding may legitimately be in. Two candidates of ``encodings.manual`` published here means the run kept both readings of "manual" alive and chose between them per test, which is what the answer's own working will say. properties: column: title: Column type: string component: anyOf: - type: string - type: 'null' title: Component name: description: The candidate's name, as a test spec cites it. title: Name type: string note: default: '' description: >- Where this reading came from — a policy sheet, a flag column, a profiled domain. title: Note type: string path: title: Path type: string slot: description: '''encodings.posted'', ''encodings.manual'', ''layers.book'', ….' title: Slot type: string table_name: title: Table Name type: string values: description: The values of that column which mean this. items: type: string title: Values type: array required: - slot - name - path - table_name - column title: BoundValueSet type: object DeepSearchClaimReference: additionalProperties: false description: A claim's address within a published SQL or command execution receipt. properties: cited_value: description: The exact value checked against the retained result. title: Cited Value type: string column: anyOf: - type: string - type: 'null' description: Result column for a cell claim; null otherwise. title: Column kind: description: How the result supports the claim. enum: - result_cell - result_count - result_absence - command_result title: Kind type: string result_id: description: The matching result_id in sql_receipts or command_receipts. title: Result Id type: string row: anyOf: - type: integer - type: 'null' description: 0-based result row for a cell claim; null otherwise. title: Row required: - kind - result_id - cited_value title: DeepSearchClaimReference type: object JetBreakdown: additionalProperties: false description: >- The tabular result behind one figure, attached by the server. What a caller asking "by FSLI and month" or "top 10 preparers" wanted, in the shape the question implies. The rows are NOT model-authored and never were: they are the cited receipt's own result, stringified and capped here, attached at finalize from :class:`SqlReceipt` rows the run already published. That is the whole design — a figure's table costs the model no output tokens and cannot carry a cell no statement returned — and it is why there is no reshaping either: the receipt's shape IS the breakdown, so a matrix the SQL never grouped by month is a wrong statement rather than a rendering problem. ``result_id`` names the receipt the rows came from, which is always one of the figure's own citations — either on ``result_ids`` or its ``exception_listing_result_id``, the two id sets the console makes openable — so the breakdown is a convenience over the payload's own working, never a second source of truth, and a reader who wants the statement, the whole bounded result or its row provenance follows that id. (When the model names a listing it did not also list in ``receipt_ids``, that id reaches the figure through ``exception_listing_result_id`` rather than ``result_ids``; both render as receipt buttons, so the table stays one click away either way.) properties: columns: description: Column names, in the statement's own result order. items: type: string title: Columns type: array result_id: description: '`sql_receipts[].result_id` of the statement these rows are.' title: Result Id type: string rows: description: >- Rows in receipt order, cells as text so a decimal, a date and a NULL all survive the wire. At most 200; a longer result sets `truncated` and stays whole on its receipt. items: items: type: string type: array title: Rows type: array truncated: default: false description: >- Whether rows were cut — either by this table's own cap or already on the receipt it came from. A capped breakdown is never read as the complete listing. title: Truncated type: boolean required: - result_id title: JetBreakdown type: object DerivationTrace: additionalProperties: false description: >- The answer's computation DAG when evidence is derived rather than extracted. properties: steps: items: $ref: '#/components/schemas/DerivationStep' title: Steps type: array title: DerivationTrace type: object TableQueryGrounding: additionalProperties: false description: >- One SQL query executed against the caller's tables while answering. The grounding behind a computed evidence: when the agent answers a count/sum/join question it runs a SQL agent over the uploaded tables, and this is the receipt — the query text and a bounded preview of what it returned. Attached to the evidence it grounds rather than published globally, so a computed figure and its computation travel together. ``source_paths`` name uploaded files, resolved server-side through the caller's access gate exactly like ``source_path`` on the evidence itself. properties: columns: items: $ref: '#/components/schemas/TableQueryColumn' title: Columns type: array grounding_reason: anyOf: - type: string - type: 'null' description: >- Qualification on grounding_status, when present. Set for 'unavailable' (explains why proof was not possible) and for 'exact' when capture succeeded but the source regions are broader than the minimal contributing set (e.g. 'regions_broad:narrowing_specs_unavailable'). None when grounding is fully exact or absent. title: Grounding Reason grounding_status: anyOf: - enum: - exact - unavailable - zero_result type: string - type: 'null' description: >- Capture-time provenance status behind this query's regions. 'exact': the exact-provenance sidecar proved every row the query read, so its 'provenance'-basis regions are trustworthy (source regions may be broader than the minimal contributing set when grounding_reason carries a 'regions_broad:…' qualifier). 'unavailable': no exact proof could be captured (a legacy result, or a statement shape the capturer cannot instrument) — no 'provenance'-basis regions are attached, never a guessed whole-table span. 'zero_result': the query matched no rows, so there is nothing to ground. None on legacy payloads and on a query with no unclaimed table left to ground. title: Grounding Status preview_truncated: default: false description: Whether the preview cut rows or columns. title: Preview Truncated type: boolean regions: description: >- Original-file coordinates for the verified claims whose source file has an addressable grid. items: discriminator: mapping: row_range: '#/components/schemas/RowRangeQueryRegion' sheet: '#/components/schemas/SheetQueryRegion' propertyName: kind oneOf: - $ref: '#/components/schemas/SheetQueryRegion' - $ref: '#/components/schemas/RowRangeQueryRegion' title: Regions type: array result_id: anyOf: - type: string - type: 'null' description: >- Stable identity of the stored query result behind this receipt. Lets the grounding-rows endpoint replay this exact query for matched-row pages beyond the regions' inline runs. title: Result Id row_count: default: 0 description: Rows in the query's full result, not in the preview below. title: Row Count type: integer rows: description: >- Leading result rows, values rendered as text — a bounded preview, never the full result. items: additionalProperties: type: string type: object title: Rows type: array source_paths: description: >- The uploaded table files this query read — directly, or through a prior result it built on — e.g. 'planning/FS GF Custom.xlsx'. items: type: string title: Source Paths type: array sql: title: Sql type: string supports_answer: default: true description: >- False for exploratory SQL the tables engine ran but did not mark as part of the answer's calculation trail. title: Supports Answer type: boolean verified: default: false description: >- True when at least one claim behind this query passed mechanical verification against the source data. Independent of 'regions': a source without an addressable grid verifies but cannot be pointed at, so an empty 'regions' never means unverified. title: Verified type: boolean required: - sql title: TableQueryGrounding type: object JetToolFailure: additionalProperties: false description: How many times one tool returned a non-success outcome this run. properties: count: description: How many times this tool×outcome pair occurred in the run. minimum: 1 title: Count type: integer outcome: description: >- Category of the non-success: ``model_retry`` (a call the run corrected: a gate refusal, a rejected argument shape or a validation retry; does not lower `quality.status`), ``command_error`` (non-zero shell exit), ``timeout``, or ``tool_error`` (the tool itself failed, for example a SQL error). enum: - model_retry - command_error - timeout - tool_error title: Outcome type: string tool: description: >- Tool name that produced the non-success outcome (for example ``run_command``). title: Tool type: string required: - tool - outcome - count title: JetToolFailure type: object JetValidationWarning: additionalProperties: false description: One output-contract check that failed open after its corrective retry. properties: check: description: >- Stable machine-readable name of the fail-open check that was not satisfied. ``specs`` covers two causes: a finding that names no committed test, and a finding computed for a test the run still declared blocked by a missing parameter. enum: - specs - scope - cycle - grain - basis - absence - bands - pointer - delivery - figures title: Check type: string status: const: failed_open default: failed_open description: >- Always ``failed_open``: the check rejected the answer once, then passed it through. title: Status type: string required: - check title: JetValidationWarning type: object SqlReplayReceipt: additionalProperties: false description: >- Immutable inputs and engine identity for independent result recomputation. properties: catalog_sha256: description: >- SHA-256 identity of the ordered source bindings used by this statement. pattern: ^[0-9a-f]{64}$ title: Catalog Sha256 type: string engine: const: duckdb description: The query engine that executed the statement. title: Engine type: string engine_threads: description: DuckDB thread count used for this execution. exclusiveMinimum: 0 title: Engine Threads type: integer engine_version: description: The query-engine version that executed the statement. title: Engine Version type: string kind: description: The verification lane appropriate for this statement. enum: - aggregate - rowset title: Kind type: string logical_plan_sha256: description: >- SHA-256 identity of the parser tree after source-position fields are removed. pattern: ^[0-9a-f]{64}$ title: Logical Plan Sha256 type: string normalized_sql: description: >- The normalized single SELECT statement to execute during independent replay. title: Normalized Sql type: string result_artifact_sha256: description: >- SHA-256 identity of the complete retained result Parquet produced by the service. pattern: ^[0-9a-f]{64}$ title: Result Artifact Sha256 type: string result_data_sha256: description: SHA-256 identity of the complete typed result rows. pattern: ^[0-9a-f]{64}$ title: Result Data Sha256 type: string result_dependencies: description: >- Earlier retained result handles read by this statement, in deterministic order. items: type: string title: Result Dependencies type: array result_digest_version: description: >- Versioned Arrow serialization scheme used for the typed-result identity. title: Result Digest Version type: string schema_version: const: 1 default: 1 title: Schema Version type: integer sql_sha256: description: SHA-256 identity of the normalized statement. pattern: ^[0-9a-f]{64}$ title: Sql Sha256 type: string required: - kind - engine - engine_version - engine_threads - normalized_sql - sql_sha256 - logical_plan_sha256 - catalog_sha256 - result_artifact_sha256 - result_data_sha256 - result_digest_version title: SqlReplayReceipt type: object SqlTableBinding: additionalProperties: false description: >- One table a receipted statement registered, in both namespaces at once. ``path`` (plus ``component`` for one tab of a workbook) is the caller's own uploaded file; ``table_name`` is the view name the statement referenced it by. Both halves are load-bearing: view names are settled per run, so SQL that hardcodes one is only replayable alongside the mapping that produced it — a statement published without its bindings cannot be re-run. properties: component: anyOf: - type: string - type: 'null' description: >- The source worksheet, including when selected alone. Null for a direct upload or a historical unnamed tab. title: Component path: description: The uploaded table file this view read, e.g. 'ledger/journal.xlsx'. title: Path type: string source_sha256: anyOf: - pattern: ^[0-9a-f]{64}$ type: string - type: 'null' description: >- SHA-256 identity of the ingested source generation behind this table binding. title: Source Sha256 table_name: description: The view name the SQL referenced this table by, for THIS run. title: Table Name type: string required: - path - table_name title: SqlTableBinding type: object ModelTokenUsage: description: >- One model's share of a run's LLM spend. Per model rather than per run alone because a single run legitimately spends on several: a search agent's own turns, the vision engine that cracked a scan, the sub-model an RLM read used. They are priced differently, so a total without this breakdown cannot be turned into money. properties: cached_input_tokens: default: 0 description: >- The share of input_tokens served from the provider's prompt cache — billed at a reduced rate, so pricing needs it separated out rather than subtracted. title: Cached Input Tokens type: integer input_tokens: default: 0 description: Prompt tokens sent to this model, cached ones included. title: Input Tokens type: integer model: description: >- Model identifier as the provider reported it, or as the caller asked for it. title: Model type: string output_tokens: default: 0 description: Completion tokens this model generated. title: Output Tokens type: integer requests: default: 0 description: Observed provider attempts, including explicitly recorded failures. title: Requests type: integer required: - model title: ModelTokenUsage type: object FilteredSearchCell: additionalProperties: false description: >- One extracted field value on one row, with its evidence (D10). ``status`` is value-level data honesty: ``not_found`` means the component was examined and the field is absent; ``ambiguous`` means present but not normalizable (e.g. money without a currency); ``unexamined`` means the extraction could not say. properties: citation: anyOf: - $ref: '#/components/schemas/Citation' - type: 'null' description: Where the value was found, with quoted source text. field: title: Field type: string item_index: default: 0 description: Position for repeated fields; 0 for scalars. title: Item Index type: integer native_display: anyOf: - type: string - type: 'null' description: >- The source cell's formatted display, when available, kept separately from its typed value. title: Native Display native_raw: anyOf: - type: string - type: 'null' description: The stored native cell value, before display formatting or rounding. title: Native Raw status: enum: - found - not_found - ambiguous - unexamined title: Status type: string value: anyOf: - discriminator: mapping: boolean: '#/components/schemas/BooleanCell' date: '#/components/schemas/DateCell' money: '#/components/schemas/MoneyCell' number: '#/components/schemas/NumberCell' text: '#/components/schemas/TextCell' propertyName: kind oneOf: - $ref: '#/components/schemas/MoneyCell' - $ref: '#/components/schemas/TextCell' - $ref: '#/components/schemas/DateCell' - $ref: '#/components/schemas/NumberCell' - $ref: '#/components/schemas/BooleanCell' - type: 'null' title: Value required: - field - status title: FilteredSearchCell type: object FilteredSearchComponent: additionalProperties: false description: A matching component and its own observations within an uploaded file. properties: category: anyOf: - type: string - type: 'null' description: The component's primary taxonomy category. title: Category cells: description: Typed observations belonging to this component. items: $ref: '#/components/schemas/FilteredSearchCell' title: Cells type: array component: description: >- Public component name — the tab or document section, matching the component= argument of the file tools (qa-file, read-file, query-tables). Several document rows can share one section name; page_start/page_end distinguish them. A media row's name is the recording stem, display-only (file tools take the whole file). title: Component type: string component_kind: description: The representation containing these observations. enum: - document - sheet - media title: Component Kind type: string content_matches: description: >- Content criteria this row satisfied, with observed values and the source passages used to verify them. items: $ref: '#/components/schemas/ContentConditionMatch' title: Content Matches type: array document_type: anyOf: - type: string - type: 'null' description: The profiled document type of this component. title: Document Type entity_id: anyOf: - type: string - type: 'null' description: The printed identifier of the matching entity within a register. title: Entity Id page_end: anyOf: - type: integer - type: 'null' description: Last source page containing the component. title: Page End page_start: anyOf: - type: integer - type: 'null' description: First source page containing the component. title: Page Start source_row: anyOf: - type: integer - type: 'null' description: The native sheet row containing this entity's facts. title: Source Row subcategory: anyOf: - type: string - type: 'null' description: The component's primary taxonomy subcategory. title: Subcategory summary: default: '' description: A description of the component's contents. title: Summary type: string required: - component - component_kind title: FilteredSearchComponent type: object ContentConditionMatch: additionalProperties: false description: A verified content criterion attached to the matching result row. properties: condition: description: The content condition evaluated after catalog filtering. title: Condition type: string evidences: description: Source passages supporting this row's satisfaction of the condition. items: $ref: '#/components/schemas/ContentEvidence' minItems: 1 title: Evidences type: array value: anyOf: - type: string - type: 'null' description: >- Observed source value supporting the match, when available as a short value. title: Value required: - condition - evidences title: ContentConditionMatch type: object DerivationStep: additionalProperties: false description: One SQL step in a table-QA derivation DAG. properties: kind: enum: - extraction - transformation title: Kind type: string label: title: Label type: string preview_rows: items: additionalProperties: type: string type: object title: Preview Rows type: array reads: description: result_ids this step depends on. items: type: string title: Reads type: array result_id: title: Result Id type: string sql: title: Sql type: string required: - result_id - sql - kind - label title: DerivationStep type: object TableQueryColumn: additionalProperties: false description: One column of an executed SQL query's result preview. properties: data_type: title: Data Type type: string name: title: Name type: string required: - name - data_type title: TableQueryColumn type: object RowRangeQueryRegion: additionalProperties: false description: >- A verified region on a pageable tabular artifact, addressed by row number. A parquet upload stored as-is uses its own row order. A jsonl or parquet derivative uses the queried artifact's row order; ``derivative_path`` names that artifact when it differs from the caller-facing ``source_path``. properties: basis: default: verified description: >- How this region was established. 'verified': a claim whose cited value was mechanically re-computed from exactly these rows. 'inputs': one table's contribution to a derived (multi-table) figure — the rows were verified to match the claim's filters, but the figure itself is not re-computable from this table alone. 'provenance': no claim covered this query, so the region records what the query's captured provenance proved it read — never a whole-table guess. Absent on legacy payloads, which are all 'verified'. enum: - verified - inputs - provenance title: Basis type: string bounding: default: false description: >- True when this is a bounding range over a large match set rather than exact runs. title: Bounding type: boolean columns: description: Cited column names, in table order. items: type: string title: Columns type: array derivative_path: anyOf: - type: string - type: 'null' description: >- Pageable derivative (parquet or jsonl) when it is not the uploaded source itself. title: Derivative Path end_row: description: Last row of the run, 0-based and inclusive. title: End Row type: integer filter_columns: description: >- Columns the verified claim filtered on to select these rows, minus any already in columns. Empty on legacy payloads. items: type: string title: Filter Columns type: array kind: const: row_range default: row_range title: Kind type: string matched_rows: default: 0 description: How many source rows the region covers. title: Matched Rows type: integer read_columns: description: >- Columns the query read from this table (output lineage), minus any already in columns or filter_columns. Populated on a 'provenance'-basis region only; empty otherwise and on legacy payloads. items: type: string title: Read Columns type: array region_id: anyOf: - format: uuid type: string - type: 'null' description: >- Opaque identity for paging this exact region when a receipt has several regions on one file. title: Region Id runs: description: >- Exact matched-row runs inside the span, so a bounding range stays pageable as matches only. May cover fewer than matched_rows when the verifier truncated its run list; empty on legacy payloads. items: $ref: '#/components/schemas/ArtifactRowRun' title: Runs type: array runs_replayable: default: false description: >- True only when grounding-rows can reconstruct this exact region predicate for pages beyond runs. Regions without a safe replay fail closed instead of returning broader rows. title: Runs Replayable type: boolean runs_truncated: default: false description: >- True when runs is an exact ordered prefix of matched islands and more matched rows exist. Later pages require guarded replay; false when the runs are complete or on legacy payloads. title: Runs Truncated type: boolean scan_index: anyOf: - type: integer - type: 'null' description: >- Which scan of the query read these rows, when the region records one scan rather than the whole table. A query can read one file more than once — a narrow CTE and a broad one, say — and each such scan grounds separately, so this identifies the scan to replay for further row pages. Absent on a whole-table span, on verified regions, and on legacy payloads. title: Scan Index scan_label: anyOf: - type: string - type: 'null' description: >- The scan named the way the query spells it: 'main query', 'CTE ', or 'subquery '. Present exactly when scan_index is. title: Scan Label source_path: description: Uploaded file path this region belongs to. title: Source Path type: string start_row: description: First row of the run, 0-based and inclusive. title: Start Row type: integer required: - source_path - start_row - end_row title: RowRangeQueryRegion type: object SheetQueryRegion: additionalProperties: false description: >- A verified region on a source file with an addressable grid. Coordinates are expressed in the caller's uploaded workbook or CSV, never in the internal parquet derivative. properties: a1_range: description: A1 range on the original sheet, e.g. 'B12:D15'. title: A1 Range type: string basis: default: verified description: >- How this region was established. 'verified': a claim whose cited value was mechanically re-computed from exactly these rows. 'inputs': one table's contribution to a derived (multi-table) figure — the rows were verified to match the claim's filters, but the figure itself is not re-computable from this table alone. 'provenance': no claim covered this query, so the region records what the query's captured provenance proved it read — never a whole-table guess. Absent on legacy payloads, which are all 'verified'. enum: - verified - inputs - provenance title: Basis type: string bounding: default: false description: >- True when this is a bounding box over a large match set rather than exact runs. title: Bounding type: boolean kind: const: sheet default: sheet title: Kind type: string matched_rows: default: 0 description: How many source rows the region covers. title: Matched Rows type: integer scan_index: anyOf: - type: integer - type: 'null' description: >- Which scan of the query read these rows, when the region records one scan rather than the whole table. A query can read one file more than once — a narrow CTE and a broad one, say — and each such scan grounds separately, so this identifies the scan to replay for further row pages. Absent on a whole-table span, on verified regions, and on legacy payloads. title: Scan Index scan_label: anyOf: - type: string - type: 'null' description: >- The scan named the way the query spells it: 'main query', 'CTE ', or 'subquery '. Present exactly when scan_index is. title: Scan Label sheet_name: anyOf: - type: string - type: 'null' description: Workbook tab, when applicable. title: Sheet Name source_path: description: Uploaded file path this region points at. title: Source Path type: string required: - source_path - a1_range title: SheetQueryRegion type: object Citation: additionalProperties: false description: Where an extracted value was found, with optional quoted source text. properties: location: description: Where in the source the value was read. discriminator: mapping: json_pointer: '#/components/schemas/JsonPointer' page_region: '#/components/schemas/PageRegion' row_range: '#/components/schemas/RowRange' sheet_range: '#/components/schemas/SheetRange' table_region: '#/components/schemas/TableRegion' text_span: '#/components/schemas/TextSpan' propertyName: kind oneOf: - $ref: '#/components/schemas/PageRegion' - $ref: '#/components/schemas/SheetRange' - $ref: '#/components/schemas/TextSpan' - $ref: '#/components/schemas/RowRange' - $ref: '#/components/schemas/TableRegion' - $ref: '#/components/schemas/JsonPointer' title: Location source_text: anyOf: - type: string - type: 'null' description: >- Short quote from the source at that location. Null when citations omit source text. title: Source Text required: - location title: Citation type: object BooleanCell: additionalProperties: false properties: kind: const: boolean default: boolean title: Kind type: string value: title: Value type: boolean required: - value title: BooleanCell type: object DateCell: additionalProperties: false properties: date: description: ISO 8601 calendar date. title: Date type: string kind: const: date default: date title: Kind type: string required: - date title: DateCell type: object MoneyCell: additionalProperties: false description: >- An amount with its original ISO currency — never converted or normalized (D9). Mixed-currency comparison and aggregation are unsupported in this version: results assume the compared records share a currency and always show it. properties: amount: description: Decimal-as-string, 2 decimal places. title: Amount type: string currency: description: ISO 4217 code as stated by the source. title: Currency type: string currency_source: default: stated description: >- How the currency was arrived at: 'stated' when the source named it, 'assumed' when the workspace's default currency disambiguated a symbol the source left open (e.g. a bare '$'). Never a conversion — the amount is always the figure the document showed. enum: - stated - assumed title: Currency Source type: string kind: const: money default: money title: Kind type: string required: - amount - currency title: MoneyCell type: object NumberCell: additionalProperties: false properties: kind: const: number default: number title: Kind type: string number: description: Decimal-as-string. title: Number type: string required: - number title: NumberCell type: object TextCell: additionalProperties: false properties: kind: const: text default: text title: Kind type: string text: title: Text type: string required: - text title: TextCell type: object ArtifactRowRun: additionalProperties: false description: One inclusive 0-based run of matched rows in the pageable artifact. properties: end: description: Last matched row of the run, 0-based and inclusive. title: End type: integer start: description: First matched row of the run, 0-based and inclusive. title: Start type: integer required: - start - end title: ArtifactRowRun type: object JsonPointer: additionalProperties: false description: An RFC 6901 pointer into a JSON source; an empty string means the root. properties: kind: const: json_pointer default: json_pointer title: Kind type: string pointer: pattern: ^(?:$|/) title: Pointer type: string required: - pointer title: JsonPointer type: object PageRegion: additionalProperties: false description: A region on a 1-based page. A bbox is a 4-point polygon. properties: kind: const: page_region default: page_region title: Kind type: string page: description: 1-based page number this region sits on. minimum: 1 title: Page type: integer polygons: description: >- One or more polygons in normalized 0-1 coordinates, used to draw overlays. items: items: maxItems: 2 minItems: 2 prefixItems: - type: number - type: number type: array minItems: 3 type: array title: Polygons type: array required: - page title: PageRegion type: object RowRange: additionalProperties: false description: A 0-based inclusive row run on a parquet table. properties: column: anyOf: - type: string - type: 'null' title: Column end_row: minimum: 0 title: End Row type: integer kind: const: row_range default: row_range title: Kind type: string start_row: minimum: 0 title: Start Row type: integer required: - start_row - end_row title: RowRange type: object SheetRange: additionalProperties: false description: A cell range on a spreadsheet sheet. properties: a1_range: description: A1 cell range on that sheet, for example B12:D15. title: A1 Range type: string kind: const: sheet_range default: sheet_range title: Kind type: string sheet: description: Workbook tab name this range belongs to. title: Sheet type: string required: - sheet - a1_range title: SheetRange type: object TableRegion: additionalProperties: false description: >- Rows and columns from a Parquet source, with reproducible SQL provenance. properties: columns: items: type: string title: Columns type: array exact: title: Exact type: boolean kind: const: table_region default: table_region title: Kind type: string matched_rows: default: 0 minimum: 0 title: Matched Rows type: integer row_ranges: items: $ref: '#/components/schemas/TableRowRange' title: Row Ranges type: array source_file_name: title: Source File Name type: string sql: title: Sql type: string required: - source_file_name - sql - exact title: TableRegion type: object TextSpan: additionalProperties: false description: A character span in derived text (optional page when known). properties: char_end: description: Exclusive end offset in the derived text. minimum: 0 title: Char End type: integer char_start: description: Inclusive start offset in the derived text. minimum: 0 title: Char Start type: integer kind: const: text_span default: text_span title: Kind type: string page: anyOf: - minimum: 1 type: integer - type: 'null' description: >- 1-based page when the span maps to a known page. Null for text-only sources. title: Page required: - char_start - char_end title: TextSpan type: object TableRowRange: additionalProperties: false description: Inclusive 0-based row range in a table source. properties: end: minimum: 0 title: End type: integer start: minimum: 0 title: Start type: integer required: - start - end title: TableRowRange type: object securitySchemes: APIKeyHeader: in: header name: X-API-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.