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

# Build a ChatPDF App

> Ship a ChatPDF-style app using Okra runtime primitives and a deployable starter

## Goal

Build a production-ready ChatPDF app with:

1. Document prepare/upload
2. Follow-up chat on a selected document
3. URL-driven document rendering
4. Minimal backend glue

## Fastest path: starter app

Use the runtime demo starter:

```bash theme={null}
cd runtime-demo/apps/vercel-pdf-pipeline-starter
npm install
cp .env.example .env.local
# set OKRA_API_KEY
npm run dev
```

Then open:

* `/chatpdf` for chat flow
* `/paper-explorer` for structured research workflow

## Core flow

```mermaid theme={null}
flowchart LR
    A[PDF URL or Upload] --> B[documents.prepare]
    B --> C[docId]
    C --> D[messages.create / completions.create]
    C --> E[doc(docId).pages[n].image.url()]
    D --> F[Chat UI]
    E --> F
```

## Runtime primitives to implement

| Capability       | Method                                              |
| ---------------- | --------------------------------------------------- |
| Prepare document | `documents.prepare({ sourceOrDocId, wait })`        |
| Track status     | `documents.status(docId)` / `documents.wait(docId)` |
| Chat turns       | `messages.create({ documentId, messages })`         |
| Direct prompt    | `completions.create({ documentId, prompt })`        |
| Page/image URLs  | `doc(docId).pages[n].image.url()`                   |

## Minimal architecture

* Client: upload/URL input + chat panel + page preview
* API routes: `session` + `ask` endpoints
* Data model: store `docId` and conversation state in your app

This keeps document parsing/orchestration out of your app runtime while preserving typed and cacheable URL surfaces.

## Production hardening checklist

1. Add role-based access and redaction policy before sharing outputs.
2. Cache stable image/page URLs at CDN edge.
3. Persist conversation history with document metadata.
4. Instrument latency and per-session cost metrics.

## Related Docs

<CardGroup cols={2}>
  <Card title="SDK" icon="rocket" href="/developers/sdk">
    End-to-end runtime API usage.
  </Card>

  <Card title="URL Builder" icon="link" href="/cookbook/url-builder">
    Deterministic URLs for rendered pages and entities.
  </Card>
</CardGroup>