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

# Quickstart

> Upload a document, parse it, and ground a value — in five minutes

This walkthrough uploads a PDF, parses it to markdown, and then locates a value inside it. You need an API key (contact your Nace representative) and `curl`.

<Info>
  Export your key once so the examples below work as-is:

  ```bash theme={"dark"}
  export NDI_API_KEY="ndi_sk_..."
  export NDI_BASE="https://ndi-api.nace.ai/api/v1"
  ```
</Info>

## Step 1 — Upload a document

Stage the file once and get back an opaque `file_id` you can reuse across every method:

```bash theme={"dark"}
curl -s "$NDI_BASE/upload" \
  -H "X-API-Key: $NDI_API_KEY" \
  -F "file=@./annual-report.pdf"
```

```json theme={"dark"}
{
  "file_id": "7f4d2a10-3b7e-4c25-9f61-8f0f4f0a1b2c",
  "file_name": "annual-report.pdf",
  "expires_at": "2026-07-18T21:04:11Z"
}
```

Reference this file in any job as `ndi://file/<file_id>`. Handles expire after about 6 days; upload again if you need the file after that.

<Tip>
  You can skip the upload entirely and pass a publicly reachable (or presigned) `https://` URL as `source_url`. See [Files & sources](/concepts/files).
</Tip>

## Step 2 — Parse it

The sync endpoint blocks until the result is ready (default 120 s, tune with `?timeout_seconds=`, max 300):

```bash theme={"dark"}
curl -s "$NDI_BASE/parse" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": { "source_url": "ndi://file/7f4d2a10-3b7e-4c25-9f61-8f0f4f0a1b2c" }
  }'
```

```json theme={"dark"}
{
  "job_id": "0c9b2c1e-8f4a-4a91-b7a5-3f2d1e0a9c8b",
  "action": "parse",
  "status": "succeeded",
  "result": {
    "result_type": "parse",
    "status": "success",
    "item": {
      "item_type": "file",
      "markdown_url": "https://…(time-limited download URL)…",
      "page_count": 96,
      "char_count": 184223,
      "extraction_duration_ms": 41250
    }
  }
}
```

Download the markdown from `result.item.markdown_url` — it is a time-limited URL (valid for 1 hour by default; re-fetch `GET /jobs/{job_id}` for a fresh one).

<Note>
  For large documents, prefer the async variant. `POST /parse_async` returns `202 {"job_id": "..."}` immediately; poll [`GET /jobs/{job_id}`](/api-reference/get-job) until `status` is `succeeded` or `failed`. The sync endpoint may itself respond `202` (server at sync capacity) or `408` (timeout) — in both cases the job keeps running and you poll the same way, so handle those two codes even when you use sync. See [Jobs](/concepts/jobs).
</Note>

## Step 3 — Ground a value

Find where "Total liabilities" appears in the source document, with coordinates:

```bash theme={"dark"}
curl -s "$NDI_BASE/ground" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": { "source_url": "ndi://file/7f4d2a10-3b7e-4c25-9f61-8f0f4f0a1b2c" },
    "items": [
      { "item_id": "liab", "query": "total liabilities", "semantic": true }
    ]
  }'
```

```json theme={"dark"}
{
  "job_id": "b1e6d5c4-2a3f-4e89-a0b1-c2d3e4f5a6b7",
  "action": "ground",
  "status": "succeeded",
  "result": {
    "result_type": "ground",
    "results": [
      {
        "item_id": "liab",
        "found": true,
        "matches": [
          {
            "match_type": "visual_region",
            "page": 42,
            "x": 0.12, "y": 0.55, "w": 0.31, "h": 0.021,
            "confidence": 0.93,
            "matched_text": "Total liabilities  $1,204,331"
          }
        ]
      }
    ],
    "total_items_found": 1,
    "total_items_requested": 1,
    "duration_ms": 8412
  }
}
```

The bounding box is normalized to the page (`x`, `y`, `w`, `h` in 0–1), so you can draw a highlight at any render resolution.

## Where to go next

<CardGroup cols={2}>
  <Card title="Jobs, polling & idempotency" href="/concepts/jobs" icon="rotate">
    Sync vs. async, statuses, retries that never double-charge you.
  </Card>

  <Card title="Categorize" href="/api-reference/categorize" icon="tags">
    Classify segments and sheets against your own taxonomy.
  </Card>

  <Card title="Files & sources" href="/concepts/files" icon="file-import">
    All the ways to get a document into NDI, plus supported formats.
  </Card>

  <Card title="Errors & limits" href="/concepts/errors" icon="triangle-exclamation">
    The error envelope, error codes, and rate limits.
  </Card>
</CardGroup>