Overview

RAVEN reads your documents and answers questions about them. You upload files — PDFs, Word documents, Excel sheets, text — and RAVEN remembers what's inside. Your application then asks RAVEN questions in plain English, and RAVEN replies with an answer plus the exact passages it pulled the answer from.

You don't run any AI models yourself. You don't manage a database. You don't pick an embedding service. RAVEN handles all of that behind the scenes. Your application just makes HTTPS calls.

1. You add documents. Upload a file, or point RAVEN at a folder in S3. RAVEN parses the text, breaks it into pieces, and stores them in a way that's searchable by meaning.
2. Your app asks a question. A normal HTTPS request with the question text.
3. RAVEN returns an answer. Plain text response with citations back to the source passages so users can verify it.

Indexing a file takes about 30 seconds. Asking a question takes 2–5 seconds.

Your app  →  POST /v1/chat  →  RAVEN  →  "The warranty is 25 years…"

Your app  →  POST /v1/search  →  RAVEN  →  [passage 1, passage 2, …]
                                              │
                                              ▼
                                          Your own AI  →  answer

You can use both at once — easy mode for general questions, custom mode for the specific endpoint where you need control.

Step 1 — Get an API key

Ask a RAVEN operator for a key. You tell them an application ID (kebab-case, like myapp or marketing-tool) and where your documents live. They hand you back one API key. Treat it like a password.

Step 2 — Add documents

Pick the path that matches where your files are.

A. From this console. Click Ingest in the left nav, drop a folder or files, click Submit. Good for trying it out.

B. Single file from your backend.

curl -X POST "$RAVEN_HOST/v1/ingest" \
  -H "X-API-Key: $RAVEN_KEY" \
  -F "file=@./contract.pdf" \
  -F "application_id=myapp" \
  -F "project_id=q1-rfp"

C. Whole folder already in S3.

curl -X POST "$RAVEN_HOST/v1/ingest/source/prefix" \
  -H "X-API-Key: $RAVEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "application_id": "myapp",
    "project_id": "q1-rfp",
    "s3_prefix": "s3://your-bucket/q1-rfp/"
  }'

Step 3 — Ask questions

Easy mode (RAVEN writes the answer):

curl -X POST "$RAVEN_HOST/v1/chat" \
  -H "X-API-Key: $RAVEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "application_id": "myapp",
    "project_id": "q1-rfp",
    "question": "What is the warranty period?"
  }'

Custom mode (RAVEN returns matching passages):

curl -X POST "$RAVEN_HOST/v1/search" \
  -H "X-API-Key: $RAVEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "application_id": "myapp",
    "project_id": "q1-rfp",
    "query": "warranty period",
    "top_k": 8
  }'

That's the whole integration. Three HTTP calls.

Every request needs the X-API-Key header. Add X-Actor-User-Id to identify which of your users triggered the action — RAVEN logs it on every audit row.

Every error response includes a request_id. Paste it in Slack and an operator can grep the access log for the full trace.