Build with the oprag API

Overview

The oprag API powers document-backed AI chatbots for your product. Upload knowledge in the dashboard, test responses with cited sources, then deploy to receive an API key for production use.

There are two surfaces: a public chat API authenticated with project API keys (sk_live_...), and a dashboard API authenticated with Cognito JWTs for managing companies, projects, documents, deployments, and keys.

Retrieval is multi-tenant: each project's documents are isolated by tenant_id and project_id in the shared Bedrock knowledge base per environment.

Base URLs

All requests use HTTPS. Pick the host for your environment:

This page is deployed to stg. Example requests below use https://api.stg.oprag.ai.

Authentication

Dashboard routes

All routes under /v1/* except POST /v1/chat and GET /v1/widget/{id}/config require a Cognito JWT from the oprag dashboard. This includes workspace summaries (/v1/dashboard/*, /v1/activity, /v1/analytics/*, /v1/billing/*, /v1/conversations/*, /v1/keys), companies, and projects:

Authorization: Bearer <Cognito JWT>

Users must have custom:tenant_id (your companyId) set after company creation. Only owners can invite another user with role: "owner". Inviting a user who already belongs to another company returns 409 Conflict.

Public chat

POST /v1/chat accepts your project API key in either header:

X-Oprag-Key: sk_live_...
# or
Authorization: Bearer sk_live_...

API keys are issued when you deploy a project from the dashboard.

Roles

Dashboard routes enforce company membership roles. Public POST /v1/chat uses API keys only.

Public Chat API

Ask questions against your project's indexed documents. Answers include cited source filenames.

Request body

{
  "question": "What is your refund policy?",
  "sessionId": "optional-session-id",
  "conversationId": "optional-conversation-id",
  "visitorId": "optional-visitor-id"
}

Response

{
  "answer": "You can cancel any time from Account → Billing...",
  "sessionId": "sess_abc123",
  "conversationId": "conv_abc123",
  "visitorId": "visitor_abc123",
  "sources": [
    {
      "title": "a1b2c3d4-billing-faq.pdf",
      "excerpt": "Refunds are available within 30 days of purchase...",
      "pageNumber": 2
    }
  ]
}

Example

curl -X POST 'https://api.stg.oprag.ai/v1/chat' \
  -H 'X-Oprag-Key: sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"question":"What is your refund policy?","sessionId":"optional-session-id","conversationId":"optional-conversation-id","visitorId":"optional-visitor-id"}'

CORS & allowed origins

API Gateway allows browser CORS from any origin at the edge. Lambda enforces per-project allowedOrigins on POST /v1/chat:

• Empty list — server-to-server calls without an Origin header are allowed; browser embeds are denied (403).
• Non-empty list — browser requests must send an Origin that exactly matches an entry (scheme and host; trailing slashes matter). Server-to-server calls without Origin are still allowed.

Set allowedOrigins on project create or update before embedding the chat widget on customer sites.

Getting an API key

1. Upload documents to your project in the dashboard and sync (or deploy — deploy also ingests pending uploads).
2. Deploy via POST /v1/projects/{id}/deploy (admin role). Issues a new sk_live_* key, revokes prior active keys, and auto-ingests uploaded documents.
3. Use the key in your integration. Keys work as soon as deploy completes — you do not need to wait for live status if documents are still indexing.

Manage keys from the dashboard or API:

• GET /v1/projects/{id}/keys — list keys (prefix only, never the full secret)
• POST /v1/projects/{id}/keys — create an additional live or test key
• POST /v1/projects/{id}/keys/rotate — rotate live key (requires an existing active key)
• DELETE /v1/projects/{id}/keys/{keyId} — revoke a key
• GET /v1/projects/{id}/integration — endpoint URL and curl example
• GET /v1/keys — list all keys across projects (workspace-level)

API routes

Full route reference. Dashboard routes require Authorization: Bearer <Cognito JWT>; POST /v1/chat, GET /health, GET /config, GET /widget.js, and GET /v1/widget/{id}/config are public. RAG-dependent routes return 503 when the knowledge base is not enabled in an environment. Route list is defined in site/src/data/api-docs.ts — keep in sync with backend/src/index.ts.

Document upload flow

Dashboard routes for ingesting files into your project knowledge base (member role):

1. Request upload URLs — POST /v1/projects/{id}/documents/upload-url (single file) or POST .../documents/bulk-upload-url (batch)
2. Upload to S3 — PUT the file to uploadUrl and metadataBody (verbatim JSON string) to metadataUploadUrl (15-minute TTL).
3. Confirm upload — POST /v1/projects/{id}/documents/{docId}/confirm — verifies S3 objects, marks uploaded, returns the document record.
4. Sync to knowledge base — POST /v1/projects/{id}/documents/sync — returns 202 Accepted; ingestion runs asynchronously (wait 1–5 minutes before chatting).

To replace an existing file, use POST .../documents/{docId}/replace-url, then confirm and sync as usual. Version history is available at GET .../documents/{docId}/versions.

Upload-url request

{
  "filename": "billing-faq.pdf",
  "contentType": "application/pdf"
}

Upload-url response

{
  "documentId": "doc_abc123",
  "uploadUrl": "https://...",
  "metadataUploadUrl": "https://...",
  "metadataBody": "{\"metadataAttributes\":{\"tenant_id\":\"...\",\"project_id\":\"...\"}}",
  "key": "documents/{companyId}/{projectId}/{uuid}-billing-faq.pdf",
  "metadataKey": "documents/.../billing-faq.pdf.metadata.json",
  "bucket": "ashutech-dev-oprag-docs-...",
  "expiresInSeconds": 900,
  "instructions": "1) PUT file to uploadUrl. 2) PUT metadataBody to metadataUploadUrl. 3) POST confirm. 4) POST sync."
}

PUT metadataBody as the raw body to metadataUploadUrl — do not JSON.stringify it again. S3 keys use {uuid}-{filename}.

Sync response (202 Accepted)

{
  "documentCount": 2,
  "statuses": ["STARTING"],
  "companyId": "...",
  "projectId": "...",
  "message": "Project-scoped ingestion started. Wait 1–5 minutes before chatting."
}

documentCount reflects uploaded/indexed documents only — not abandoned presigns. POST .../deploy also confirms pending uploads and ingests documents, so a separate sync before deploy is optional. Searchability may lag a few minutes after sync or deploy.

Error responses

Errors return JSON with an error string and the appropriate HTTP status:

{
  "error": "question is required"
}

Health

Liveness probe — no authentication required. Use for uptime monitoring and deploy smoke tests.

curl 'https://api.stg.oprag.ai/health'

Response

{
  "status": "ok",
  "service": "oprag-api",
  "timestamp": "2026-06-09T12:00:00.000Z"
}