--- title: "playground_ground" method: POST path: "/v1/playground/ground" tags: ["playground"] --- # playground_ground `POST /v1/playground/ground` ## Request - Base URL: `https://ndi-api.nace.ai` (the document declares no server; this is the origin it was published from) - URL: `https://ndi-api.nace.ai/v1/playground/ground` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Locate caller-provided text under the anonymous playground try budget. ## Query parameters - `wait_seconds` integer: 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`. ## Headers - `cf-turnstile-response` string, nullable ## Request body `multipart/form-data` - BodyPlaygroundGroundV1PlaygroundGroundPost - `file` string, binary, required - `targets` string, required - `parse` string, nullable: Optional JSON object of parse settings, shaped like the `parse` section of the API request. - `cf-turnstile-response` string, nullable ## Response `202` Successful Response - GroundJob - `job_id` string, uuid, required: Server-minted id. Poll GET /v1/jobs/{job_id} or pass wait_seconds on create. - `kind` 'ground' - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled', required: ``cancelled`` is a first-class terminal status, not a ``failed`` variant. Conflating them makes error-rate metrics lie and forces every client to string-match an error code. - `name` string, nullable: 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}. - `project_id` string, uuid, nullable: Caller-minted grouping id shared by jobs submitted together. Filterable on GET /v1/jobs. - `workspace_id` string, uuid, nullable: The workspace this job reads. Null for a document operation whose source is an upload, a URL, or a prior parse result. - `idempotency_key` string, nullable: Key that was replayed to return this job. Absent when the create call had no Idempotency-Key. - `force` boolean, nullable: 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. - `source` union: 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 — both `workspace_file` and `upload` sources remain until explicit deletion. Read from the stored request, so it rides the same retention path as `query` and `result`: null once `result_state` leaves `available`. - UploadSource: Bytes staged through ``POST /v1/uploads``. Retained until explicit deletion, except under Zero retention. - `type` 'upload' - `upload_id` string, uuid, required: Id returned by POST /v1/uploads. Ordinary bytes remain until their consuming jobs or tenant are deleted. - UrlSource: A public or presigned HTTPS location we fetch server-side. - `type` 'url' - `url` string, required: HTTPS URL the service fetches. - `file_name` string, required: Filename to record for the fetched bytes. - WorkspaceFileSource: 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. - `type` 'workspace_file' - `workspace_id` string, uuid, required: Workspace that owns the file. - `file_id` string, uuid, required: File id from GET /v1/workspaces/{workspace_id}/files. - ParseResultSource: A prior Parse job whose parsed artifact can be reused by downstream methods. - `type` 'parse_result' - `job_id` string, uuid, required: Succeeded parse job whose artifact should be reused. - `query` string, nullable: The question this job was asked, for the search kinds that carry one (intelligent_search, qa_file, qa_tables, filtered_search); null for every other kind. Read from the stored request, so it rides the same retention path as `result`: null once `result_state` leaves `available`. Narrow by design — the frozen access context never reaches the wire. File scope is summarised separately as `query_scope`. - `query_scope` union: 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. - WorkspaceQueryScope: The question ran against the whole workspace. - `type` 'workspace' - FileQueryScope: The question ran against one workspace-relative file. - `type` 'file' - `path` string, required - PathPrefixQueryScope: The question ran against one folder subtree. - `type` 'path_prefix' - `prefix` string, required - FilesQueryScope: The question ran against several files; only the count is public. - `type` 'files' - `count` integer, required - `effort` string, nullable: 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`. - `surface` 'deep_search' | 'qa' | 'workbook', nullable: 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`. - `progress` JobProgress: Absent until the job is ``running``. - `units_total` integer, nullable - `units_done` integer - `items_total` integer, nullable: Files, for batch kinds. - `items_done` integer - `items_failed` integer: Quarantined after exhausting retries, for batch kinds. Excluded from items_done. - `stage` string, nullable: Current pipeline stage, for display only. - `knowledge_graph` KnowledgeGraphBuildProgress: 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. - `phase_index` integer, required: 0-based position of the current phase in the build's fixed run order; equals phase_count when done. - `phase_count` integer, required: How many phases a build passes through before it is done. Currently 9. - `countable` boolean, required: 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. - `documents` integer, nullable: Documents registered from the corpus, once the registering phase has run. - `mentions` integer, nullable: Mentions extracted across the corpus, once the validating phase has run. - `step` string, nullable: 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. - `step_done` integer, nullable: Units of `step` finished, when it has countable units. - `step_total` integer, nullable: Units `step` has to get through, when that is known. - `routing` AutomaticSearchRouting - `selected` 'fact' | 'agent' | 'deep' | 'filtered', required: The route the router chose, the one the request's `mode` named, or `fact` when nothing was searched: the workspace had no ingested files, or the query asked for nothing that a document contains. - `final` 'fact' | 'agent' | 'deep' | 'filtered', required: The pipeline that produced the returned output. It differs from `selected` only in `auto` mode, when the router chose fact search, fact search could not settle the question, and the agent answered instead. - `reason` string, required: The router's explanation of its decision, or why no router ran. - `router_model` string, required: The model used to choose the search pipeline; `none` when no router ran. - `router` union: Which router decided, and what it measured: an LLM (its explanation is ``reason``), NaceDM (its probability and decision point), or `requested` when no router ran: the request's `mode` was `fact` or `agent`, or the workspace had no ingested files. Results routed before this field existed read as the LLM. - AutomaticLlmRouter: An LLM chose the route. Its explanation is the routing's ``reason``. - `kind` 'llm' - AutomaticNaceDmRouter: NaceDM, the decision model, chose the route by scoring how likely the query needs the agent. - `kind` 'nacedm' - `p_agent` number, nullable, required: 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. - `decision_point` number, required: The agent runs when ``p_agent`` is at or above this; fact search runs below it. - AutomaticRequestedRouter: No router ran: the request's ``mode`` named the route, or the workspace had no ingested files. - `kind` 'requested' - `router_wall_ms` integer, nullable: Wall time spent selecting the initial route. - `fact_wall_ms` integer, nullable: Wall time spent running fact search, when selected. - `delegated_wall_ms` integer, nullable: Wall time spent preparing and running the native deep or filtered job. - `result` NdiServiceAppPlatformApiResultsGroundResult - `result_type` 'ground' - `targets` GroundTargetResult[], required: One result per request target, in request order. - `id` string, required: Caller-defined id from the request targets list. Join request to result on this, not on quote text. - `status` 'found' | 'not_found' | 'failed', required: Per-target outcome: found has at least one location, not_found means the quote is not in the document (the job still succeeded), failed is a target-level error. - `matches` GroundMatch[]: Locations for this target, sorted best-first and numbered by rank. Empty when not found. - `word_anchor` WordAnchor: Native OOXML paragraph span, independent of converted-PDF pagination. - `part` string, required: OOXML package member containing the matched paragraph. - `paragraph_index` integer, required: Zero-based w:p index in this part, counting start tags including table-cell paragraphs. - `char_start` integer, required: Inclusive code-point offset in visible paragraph text: w:t runs joined with tabs and breaks. - `char_end` integer, required: Exclusive code-point offset in the same paragraph text. - `rank` integer, required: 1-based position in this target's matches after the matcher has sorted hits best-first. 1 is the primary location; later ranks are other occurrences or weaker hits. On an HTML source, a hint ranks the visible occurrence nearest that nearby text first; without a hint, rank 1 is the first visible occurrence. Rank restarts at 1 on every target. The list is capped by options.max_matches. Not a score — use match_method and confidence. - `matched_text` string, required: The string actually found at location. Can differ from the request target text when match_method is normalized or semantic. - `match_method` 'exact' | 'normalized' | 'semantic', required: How this hit was accepted: exact is a character-for-character copy of the target, normalized ignores case and punctuation, semantic is a meaning-similar or visual hit. - `confidence` number, nullable: 0-1 locator confidence when the grounding provider reports one. Independent of match_method: exact and normalized hits can carry a score too. Null only when the provider has no confidence for that match. This is not rank. - `location` union, required: Where the quote was found. Kind follows the source: page_region for PDF or image polygons, text_span for character offsets — into the derived text for most sources, but into the uploaded file itself for HTML and email, so tags and headers are counted — sheet_range for a workbook tab and A1, json_pointer for JSON, jsonl_record for a JSONL line, row_range for table rows, or audio_range for media timestamps. - union - PageRegion: A region on a 1-based page. A bbox is a 4-point polygon. - … - SheetRange: A cell range on a spreadsheet sheet. - … - TextSpan: A character span in derived text (optional page when known). - … - RowRange: A 0-based inclusive row run on a parquet table. - … - TableRegion: Rows and columns from a Parquet source, with reproducible SQL provenance. - … - JsonPointer: An RFC 6901 pointer into a JSON source; an empty string means the root. - … - union - TextRange: A character span in a derivative's text, with the page(s) it falls on. ``pages`` is every page the span overlaps — a chunk that straddles a page marker belongs to both, and a reader handed only the first would miss the part of the span that carries the match. ``page`` is the first of them, kept because most producers and consumers only ever deal in one page. - … - VisualRegion - … - SpreadsheetRange - … - JsonlRecord - … - JsonPointer: An RFC 6901 pointer into a JSON source; an empty string means the root. - … - AudioRange - … - RowRange: A 0-based inclusive row run on a parquet table. - … - `cropped_image_url` string, nullable: Crop URL when options.include_previews is true and the match has a visual region. - `error` string, nullable: Machine-readable reason when status is failed, for example needle_too_short. Null otherwise. - `units` integer, required: Measured work units for this ground job. The job's `credits` is the final billed amount. - `transcript_url` string, nullable: Storage URL of the MediaTimeline JSON used for grounding. - `converted_pdf_url` string, nullable: PDF the office source was converted to before grounding. Match regions are measured on this PDF. Null when the source was already a PDF or did not need conversion. - `warnings` string[]: Parse settings this run accepted but did not apply, each naming the setting and why, for example a page selection on a file with no pages. Left out when empty. - `result_state` 'available' | 'expired' | 'not_retained' | 'cancelled' | 'storage_unavailable': Why ``Job.result`` is null. ``available`` with a null result means the job has not succeeded yet; ``expired`` means its content was removed; ``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 not charged, including delivered parts) — 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. ``storage_unavailable`` withholds a retained result while its workspace binding refuses access; ``Job.result_error`` explains the current refusal. 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. - `result_error` Error: The error object, per spec 12 §1.8. - `code` 'storage_connection_not_found' | 'storage_connection_in_use' | 'storage_limit_exceeded' | 'storage_conflict' | 'storage_auth_required' | 'storage_unavailable' | 'scan_required' | 'scan_rejected' | 'scan_unavailable' | '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', required: 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. - `message` string, required: Human- and model-readable; says what to do differently. - `detail` object, nullable: Structured payload, when the code carries one. - `retryable` boolean, required: Whether retrying the identical request could succeed. - `request_id` string, nullable: 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. - `error` Error: The error object, per spec 12 §1.8. - `code` 'storage_connection_not_found' | 'storage_connection_in_use' | 'storage_limit_exceeded' | 'storage_conflict' | 'storage_auth_required' | 'storage_unavailable' | 'scan_required' | 'scan_rejected' | 'scan_unavailable' | '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', required: 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. - `message` string, required: Human- and model-readable; says what to do differently. - `detail` object, nullable: Structured payload, when the code carries one. - `retryable` boolean, required: Whether retrying the identical request could succeed. - `request_id` string, nullable: 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. - `units` integer: Measured work in legacy credit units, retained even when a failed or cancelled job is not billed. Kept for compatibility: `credits` is the authoritative billed amount. - `credits` integer, nullable: 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. Failed and cancelled-before-completion jobs finalize with 0 credits, including delivered parts; ones finalized before that policy keep their credits. Always null on a stage job that Automatic Search delegated: its work is billed on the parent job. - `usage_final` boolean: 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. - `credit_schedule_version` integer, nullable: Version of the credit schedule `credits` were priced under. Null until `usage_final` is true. - `usage_finalized_at` string, date-time, nullable: When `credits` became final. Null until `usage_final` is true. - `cost` JobCost: An immutable USD price independent of the legacy credit schedule. - `currency` 'USD' - `pricing_version` string, required: The dollar price-sheet version pinned when this job was accepted. - `total_usd` string, required: Sum of the component amounts in USD, serialized as a decimal string. - `lines` CostLine[], required: The independently priced Parse and operation components, including paid reuse. - `operation` 'parse' | 'split' | 'classify' | 'extract' | 'ground', required: The work this dollar amount pays for. - `quantity` integer, required: The number of page-equivalents or Ground targets priced by this line. - `unit` 'page' | 'item', required: The quantity's billing unit: page-equivalent or Ground target. - `execution` 'fresh' | 'reused', required: The price tier: normal work or verified, billing-eligible tenant reuse; not provider token caching. - `unit_price_usd` string, required: USD per unit under the job's pinned price sheet, serialized as a decimal string. - `amount_usd` string, required: This line's USD amount: quantity multiplied by unit_price_usd, serialized as a decimal string. - `reuse_reason` 'reused_parse' | 'repeat_of_job', nullable: Why the lower reuse rate applies; null on a normal-price line. - `usage` JobUsage: How a job's final credits were computed. - `lines` UsageLine[], required: One line per part. Their credits sum to the job's credits; waived parts remain listed at 0 credits. - `part` 'parse' | 'operation' | 'image_ocr', required: parse: reading the document into text. operation: the tool's own work on what was parsed. image_ocr: reading the images inside an email, HTML or spreadsheet file. A ground job's image_ocr is the email images it read to find targets its text search missed. - `quantity` integer, required: How many units of work this part measured, including waived or included work. - `unit` 'page' | 'item' | 'unit' | 'image', required: 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, image is an image Parse read inside an email, HTML or spreadsheet file, unit is a job priced by its units directly (agent steps). - `credits_per_unit` integer, required: The credit schedule's rate for one unit of this part; zero for OCR included in the ordinary price. - `multiplier` integer, required: 2 on the parse and image_ocr parts of a parse_mode "high" job, otherwise 1. - `credits` integer, required: quantity x credits_per_unit x multiplier: what this part added to the job's credits. 0 when waived or included in the ordinary price. - `waiver` UsageWaiver: Why part of a job, or the whole job, was not charged. - `part` 'parse' | 'job', required: parse: the parse part was not charged. job: nothing in the job was charged. - `reason` 'reused_parse' | 'repeat_of_job', required: 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. - `source_job_id` string, uuid, nullable: Always null: billing history must not disclose another job as its visibility changes. - `created_at` string, date-time, required: When the job row was created. - `started_at` string, date-time, nullable: When execution began. Null while still queued. - `finished_at` string, date-time, nullable: When the job reached a terminal status. - `payload_expires_at` string, date-time, nullable: Cleanup deadline after explicit deletion. Null for retained content; Zero retention uses its delivery window. - `deleted_at` string, date-time, nullable: 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`. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `402`: Payment Required - `403`: Forbidden - `404`: Not Found - `409`: Conflict - `410`: Gone - `413`: Request Entity Too Large - `422`: Unprocessable Entity - `424`: Failed Dependency - `429`: Too Many Requests - `500`: Internal Server Error - `501`: Not Implemented - `503`: Service Unavailable - `504`: Gateway Timeout --- [API](https://skmtc.dev/nace/apis/ndi-service.md) - [All operations](https://skmtc.dev/nace/apis/ndi-service/llms.txt) - [OpenAPI document](https://skmtc.dev/nace/apis/ndi-service/revisions/d9d1f8ec2207?raw)