Ground quoted text

Ground locates target text. It is target location, not claim verification. After a fact, deep, or journal-entry-testing search, do not start a new Ground job. Poll result.grounding_job_ids instead — see Search a workspace. Use this endpoint for standalone quotes, or for search jobs that predate that field.

Python
TypeScript
curl

from ndi_sdk import NdiClient
from ndi_sdk.models.document_ops import GroundTarget

with NdiClient() as client:
    upload = client.documents.create_upload("report.pdf")
    job = client.jobs.wait(
        client.documents.ground(
            upload,
            targets=[GroundTarget(id="total", text="1,200.50")],
            wait_seconds=30,
        ).job_id
    )
    for target in job.result.targets:
        for match in target.matches:
            print(target.id, match.matched_text, match.location)

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
const job = await client.jobs.wait(
  (
    await client.documents.ground(upload, {
      targets: [{ id: "total", text: "1,200.50" }],
      wait_seconds: 30,
    })
  ).job_id,
);
console.log(job.result);

UPLOAD_ID=$(curl -s -X POST "$NDI_BASE_URL/v1/uploads" \
  -H "X-API-Key: $NDI_API_KEY" \
  -F "file=@report.pdf" | jq -r '.upload_id')

curl -s -X POST "$NDI_BASE_URL/v1/ground?wait_seconds=60" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\":{\"type\":\"upload\",\"upload_id\":\"$UPLOAD_ID\"},\"targets\":[{\"id\":\"total\",\"text\":\"1,200.50\"}]}"

Pass 1–30 targets. Optional hint (nearby context) and sheet (spreadsheet tab) disambiguate a repeated quote. On an HTML source, hint is nearby visible text: the occurrence nearest that text ranks first. Without a hint, rank 1 is the first visible occurrence. semantic=true is deprecated for now: a target that sets it can come back with status failed and error semantic_mode_deprecated. A JSON quote that names several fields is matched as a subset of one node: every named field must be present, extra fields on the node are ignored, and [] / {} stand for any array or object. If a target is itself a JSON object and the literal search misses, the matcher retries that object as a subset pattern and keeps the hit only when exactly one node matches. A stitched field-run quote ("period": "2024", ..., "accounts": [...]) is first repaired into an object ([] / {} for elisions) and then run through the same unique-subset check. Set options.include_previews=true to mint crop URLs; fetch them with the same API key via client.jobs.ground_crop or GET /v1/jobs/{job_id}/ground-crops/{artifact_ref}. An HTML source is matched against the text a browser would paint. Markup a reader never sees is skipped: the contents of script and style, anything under a hidden or aria-hidden="true" attribute, a <dialog> without open, and anything its own style attribute hides (display:none, visibility:hidden, a zero opacity). Attribute values are never matched, so a phrase that appears only in a <title>, an alt or a social-preview tag is not returned. Hiding is read from the markup itself rather than from a browser, so a stylesheet or a media query that hides a phrase — a nav that collapses on small screens, say — is not evaluated, and such a phrase can still be returned. Offsets count from the start of the uploaded HTML, tags included. A parse_result source is supported. See Ground response.

Getting started

Guides

Agents

Concepts

Troubleshooting