> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rcintell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Your policy documents

> Upload a payer PDF, get a cited folder tree, then ask — separate from GET /v1/policies

Two lanes. Do not mix them.

| Lane              | Who owns the PDF                   | API                                       | Writes `GET /v1/policies`? |
| ----------------- | ---------------------------------- | ----------------------------------------- | -------------------------- |
| **Posted payers** | RCIntel (UHC, Anthem, Medicare, …) | `GET /v1/policies`                        | Yes — our mart only        |
| **Your folder**   | You (manuals, contracts, PA lists) | `POST /v1/policy/parse` then `/structure` | **Never**                  |

Facts extracted from an upload stay on that document. They do not become United or Anthem coverage in the public lookup.

<Info>
  Schema for these routes is in [API Reference → Your documents](/api-reference). A `kp_test_` key on sandbox can call them so you can see a live response. Sandbox posted-payer inventory is a **sample** — see [Payer policies](/docs/policies). Do not send PHI on a test key.
</Info>

## What exists today (use this first)

Before asking for more payers, exercise what already returns cited rows:

| Source           | `GET /v1/policies`                      | Notes                                                               |
| ---------------- | --------------------------------------- | ------------------------------------------------------------------- |
| Medicare FFS     | `payer=medicare_ffs`                    | NCD / LCD / MAC. Add `state` for MAC scope                          |
| UnitedHealthcare | `payer=uhc` + `plan_type=commercial`    | \~2,500 commercial rows. Try `code=99202` or `81479` before `99213` |
| Anthem           | `payer=anthem` + `plan_type=commercial` | Sandbox sample from posted Clinical UM HTML. Try `00100` or `A0427` |
| Aetna            | `payer=aetna` + `plan_type=commercial`  | Sandbox sample from posted CPBs. Try `93306` or `81161`             |

Empty is the contract. Do not treat a Medicare row as a commercial answer.

The website [Payer Intelligence](https://rcintell.com/tools/payer-intelligence) tool is the **your folder** lane: upload → parse → folder tree → cited ask.

## Parse

`POST /v1/policy/parse` — multipart file (preferred) or JSON `bytes_b64`.

| Field                 | Required          | Notes                                                   |
| --------------------- | ----------------- | ------------------------------------------------------- |
| `document_id`         | yes               | Stable id you choose; re-parse replaces chunks          |
| `file` or `bytes_b64` | yes               | PDF with a text layer. Scans return 422 `no_text_layer` |
| `user_uid`            | admin secret only | Ignored for API keys — stored as `tenant:<your tenant>` |
| `filename`            | no                | Shown in citations                                      |
| `keywords`            | no                | Optional boost list                                     |

Files ≥ 2 MB return `202` + `job_id`. Poll `GET /v1/policy/parse/{job_id}` with the same key.

```bash theme={null}
curl -X POST https://sandbox.rcintell.com/v1/policy/parse \
  -H "X-API-Key: kp_test_YOUR_TEST_KEY" \
  -F document_id="sample-pa-packet" \
  -F filename="sample-pa.pdf" \
  -F file=@sample-pa.pdf
```

## Structure (folder tree)

After parse, `POST /v1/policy/structure` builds a cached tree (reimbursement, coding, prior auth, …). Leaves cite source pages. `rebuild: true` recomputes.

```bash theme={null}
curl -X POST https://sandbox.rcintell.com/v1/policy/structure \
  -H "X-API-Key: kp_test_YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_id":"sample-pa-packet"}'
```

`GET /v1/policy/structure/sample-pa-packet` with the same key returns the cache.

`built_with` is `deterministic` or an LLM model id when enrichment is configured. Deterministic is enough for a folder UI. Field list: [API Reference](/api-reference). The live object is whatever the API stored for that document — we do not invent a sample tree.

## Ask (cited Q\&A)

`POST /v1/policy/retrieve` ranks chunks for a question. The website ask path uses that retrieve step, then only shows excerpt-backed claims.

```bash theme={null}
curl -X POST https://sandbox.rcintell.com/v1/policy/retrieve \
  -H "X-API-Key: kp_test_YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_id":"sample-pa-packet","query":"What requires prior authorization?"}'
```

Response is ranked chunks (`text`, `page_start` / `page_end`, `query_score`) — not a generated answer. Full field list: [API Reference](/api-reference).

Do not send upload text into `GET /v1/policies`.

## Findings (later)

`POST /v1/policy/findings` diffs extracted facts against our L4 payer rules. `user_findings` are safe to show; `admin_findings` and `GET /v1/policy/enrichment-candidates` are operator-only. Use after you have real documents in the folder — not as the first integration.

## Auth

| Caller                   | Header                 | Host                   | Isolation                                  |
| ------------------------ | ---------------------- | ---------------------- | ------------------------------------------ |
| Evaluation / integration | `X-API-Key: kp_test_…` | `sandbox.rcintell.com` | Chunks stored under `tenant:<your tenant>` |
| After upgrade            | `X-API-Key: kp_live_…` | `api.rcintell.com`     | Same paths, same isolation                 |
| Website workspace        | `X-Admin-Secret`       | sandbox or prod        | You pass `user_uid` (signed-in account)    |

Playground does not upload PDFs — it is for posted lookups. Schema for this lane is in API Reference regardless. Keys minted before this surface shipped need a remint (allowlist is stored at mint time). Free quota still applies. Text-layer PDFs only; no PHI on test keys.

`POST /v1/policy/findings` and `GET /v1/policy/enrichment-candidates` stay on `X-Admin-Secret` (operator). See [authentication](/docs/authentication) and [test mode](/docs/test-mode).