# DeepRAG — API Reference (Debug Only)

> **Stop.** In a coded agent, use the resume-trigger models (`Create*` / `Wait*` from `uipath.platform.common`) with plain `interrupt()` — see [impl-python.md](impl-python.md). The runtime calls these endpoints for you with the correct headers, body shape, and folder context.

This file lists endpoints for direct invocation from outside an agent (custom tooling, scripts, debugging). Request body shapes evolve with the SDK — **trust the SDK source, not this file**:

- Request specs: `uipath/platform/context_grounding/_context_grounding_service.py` in the installed venv (look for `_*_creation_spec` and `_*_retrieve_spec` methods)
- Pydantic models (input + response): `uipath/platform/context_grounding/context_grounding.py`
- Resume-trigger models: `uipath/platform/common/interrupt_models.py`
- Public docs: <https://uipath.github.io/uipath-python/>

## Verified Endpoint Paths

| Verb | Path | Purpose |
|---|---|---|
| POST | `/ecs_/v2/indexes/createephemeral` | Create an ephemeral index over attachments (`usage`: `DeepRAG` or `BatchRAG`) |
| GET  | `/ecs_/v2/indexes/{id}` | Read index metadata, including `lastIngestionStatus` |
| POST | `/ecs_/v2/indexes/{index_id}/createDeepRag` | Start a DeepRAG task |
| POST | `/ecs_/v2/indexes/{index_id}/createBatchRag` | Start a BatchTransform task (the SDK calls it BatchRag internally) |
| GET  | `/ecs_/v2/deeprag/{id}` | Read DeepRAG task status + content |
| GET  | `/ecs_/v2/batchRag/{id}` | Read BatchTransform task status + result-file metadata |

All endpoints require either `x-uipath-folderkey` or `x-uipath-folderpath` header.

## Common Errors

| Status | Body fragment | Cause | Fix |
|---|---|---|---|
| 400 | `"A folder is required for this action."` | Missing folder header | Set `UIPATH_FOLDER_KEY` env var; in coded agents, pass `index_folder_key` on the resume-trigger model |
| 400 | `"Summarization requires a successfully completed ingestion process."` | Index not ingested yet | The runtime waits on the index event when you yield `CreateEphemeralIndex`. Hitting this from direct API calls means you skipped the ingestion poll. |
| 400 | `"The Prompt field is required."` | Empty `prompt` | Pass non-empty prompt |
| 400 | `outputColumns` validation | Name regex / length | See `BatchTransformOutputColumn` in `context_grounding.py` |
| 403 | `"User is missing required index permissions."` | Role lacks index permission in folder | Use a folder where the user / agent identity has rights (personal workspace key is the safe default) |
| 404 | `"Folder does not exist or the user does not have access..."` | Folder name typo or no access | Verify with `sdk.resource_catalog.search_async` |

## Why Not Document Body Shapes Here

Inline JSON shapes drift the moment the SDK changes a field name (e.g., `enableWebSearchGrounding` vs `useWebSearchGrounding`, `globPattern` vs `targetFileGlobPattern`, `Footnote` citation mode that does not exist). Reading the SDK's `_*_creation_spec` methods gives the exact body the platform accepts at the version you are running against. Any inline copy here will be wrong eventually.