Quickstart

A test key answers with a fixed response without touching your documents, so you can prove out keys, headers, and error handling on an empty project and only then worry about ingestion.

1. Create a test integration key

   In the dashboard, open your project and create an integration key in test mode. It starts with sk_test_.

2. Ask a question

   curl -X POST 'https://api.dev.oprag.ai/v1/chat' \
     -H 'X-Oprag-Key: sk_test_...' \
     -H 'Content-Type: application/json' \
     -d '{"question":"What is your refund policy?"}'

   Copy

3. Read the response

   {
     "answer": "This is a test response from oprag. Your integration is working correctly. Replace this with a live key to get real answers from your documents.",
     "sources": [],
     "conversationId": "conv_abc123",
     "sessionId": "sess_abc123"
   }

   Copy

   If you get this back, your key, your header, and your base URL are all correct. Note that the test fixture omits type — real responses carry it, and clients treat a body with answer and no type as the answer branch.

4. Handle both response branches

   A live response is a union. Write the branch now, while there is nothing to debug — see the chat reference.

   const res = await fetch(`${apiBase}/v1/chat`, {
     method: "POST",
     headers: { "X-Oprag-Key": process.env.OPRAG_SECRET_KEY!, "Content-Type": "application/json" },
     body: JSON.stringify({ question }),
   });
   
   if (!res.ok) {
     // The error envelope is { "error": "message" } — there is no code field.
     const { error } = await res.json();
     throw new Error(`${res.status}: ${error}`);
   }
   
   const data = await res.json();
   if (data.type === "lead_capture_prompt") {
     renderLeadForm(data.promptMessage, data.fields);
   } else {
     render(data.answer, data.sources ?? []);
   }

   Copy

5. Switch to live

   Ingest documents through the document flow, then swap sk_test_ for sk_live_. Nothing else changes.