Most teams do not need a custom retrieval stack on day one. They need a reliable way to turn PDFs and Markdown into cited answers their product can call. This workflow walks through the path from first upload to a production-ready REST integration on Oprag’s AWS.
Upload docs → Validate in dashboard → Create API key → POST /v1/chat → Show answer + citationsWhat you are building
Your app sends a user question to Oprag. Oprag searches the documents you uploaded for that project, generates an answer, and returns page-level citations. Your UI shows the answer plus links back to source pages. Tenant data stays isolated per company and project — Oprag runs on our AWS infrastructure, not inside your AWS account.
Step 1 — Create a project and upload docs
Sign up (no credit card on Starter), create a project, and upload the files your users will ask about: help-center exports, policy PDFs, onboarding guides, or internal Markdown.
Tips for better answers:
- Split very large PDFs into logical sections when possible
- Use descriptive filenames — they appear in the dashboard
- Re-upload when docs change; indexing happens automatically
Step 2 — Validate answers in the dashboard
Before you wire the API into your app, ask real questions in the dashboard chat. Check three things on every reply:
- Accuracy — Does the answer match the source material?
- Citations — Do page references point to the right location?
- Refusals — When the doc does not cover a topic, does the model say so instead of guessing?
This validation step saves weeks of debugging bad embeds in production. See validate document Q&A before launch for a structured checklist.
Step 3 — Create an API key
From project settings, generate an API key scoped to that project. Store it in your secrets manager — never commit keys to git. Starter includes full API access so you can integrate while still on the free tier.
Step 4 — Call the chat endpoint
Send a POST request with the user question and optional sessionId for follow-ups. The response includes the assistant message and an array of citations with document name and page number.
curl -X POST "https://api.oprag.ai/v1/chat" \
-H "X-Oprag-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"question": "What is your refund policy for annual plans?"}'You can also pass the key as Authorization: Bearer YOUR_API_KEY. The request body field is question, not message.
The schema is the same in sandbox and production — one key, one contract. Full reference: API docs.
Step 5 — Render citations in your UI
Do not hide sources behind a tooltip. Show them inline or in a sidebar so users (and your support team) can verify before acting on an answer.
A simple pattern:
- Display the assistant reply as markdown or plain text
- List citations below with links to your hosted doc URLs or internal viewer routes
- Log citation clicks to see which docs need updates
Step 6 — Ship and monitor
Roll out to a small user cohort first. Track:
- Questions with zero citations (possible doc gap)
- Repeated questions (content or UX issue)
- Citation click-through (signals trust)
When docs change, upload new versions and spot-check a few golden questions again in the dashboard.
Common mistakes
- Skipping dashboard validation — API integration is fast; fixing bad answers in production is not
- Mixing projects — One API key per project keeps tenant isolation clean
- Expecting customer AWS deployment — Oprag hosts and isolates data on our AWS; you integrate via API and embed
Next steps
- Embed a cited chat widget if you want a drop-in UI
- Compare DIY RAG vs managed document Q&A if you are still evaluating build vs buy