Overview

RAVEN reads your documents and answers questions about them. You add files — PDFs, Word docs, Excel sheets, images, plain text — and RAVEN parses them, breaks them into passages, and indexes them so they're searchable by meaning. Your application then asks questions in plain English over HTTPS, and RAVEN replies with a written answer plus citations back to the exact source passages.

You don't run any AI models, manage a vector database, or pick an embedding service. RAVEN handles parsing, chunking, embedding, retrieval, reranking, and answer generation behind one API. Your app just makes authenticated HTTPS calls.

RAVEN is modular. You can use the whole pipeline (documents in, cited answers out) or just one piece — retrieval only, batch question-answering, structured table/key-value lookup, or document management. Pick what you need; ignore the rest. See Building blocks below.

Base URLs — production https://raven.cia.terabase.tools, staging https://raven-staging.cia.terabase.tools. The examples below use $RAVEN_HOST for the base URL and $RAVEN_KEY for your API key.

1 — Get a key and a namespace from an operator

Ask a RAVEN operator for an API key. You give them an application id (kebab-case, like traceline or marketing-tool) and one or more project ids. Each application_id + project_id pair forms a namespace — written application_id/project_id — which is the isolation boundary for your documents. The operator hands back one key scoped to your application's namespaces. Treat it like a password.

Throughout the API you can pass application_id + project_id as two fields, OR pass a single namespace string. They're equivalent — pick whichever is cleaner for your call site.

2 — Verify the key

curl "$RAVEN_HOST/v1/ready" \
  -H "X-API-Key: $RAVEN_KEY"
# → 200 {"status": "ready", "services": {...}}

3 — Add documents

Stage your files in an allow-listed S3 bucket, then ingest one by name:

curl -X POST "$RAVEN_HOST/v1/ingest/source" \
  -H "X-API-Key: $RAVEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "application_id": "myapp",
    "project_id": "q1-rfp",
    "source_uri": "s3://raven-sources-.../myapp/q1-rfp/contract.pdf"
  }'
# → 202 {"job_id": "...", "status": "queued", ...}

This returns immediately with a job id; indexing happens in the background (a few seconds for small text files, longer for large PDFs). Poll GET /v1/jobs/{job_id} for progress, or subscribe a webhook (step 5). To bulk-discover everything under a prefix, use POST /v1/ingest/source/prefix — note it only catalogs files; you then select which ones to index (see Building blocks → Ingestion).

4 — Ask questions

Let RAVEN write the answer with citations:

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?"
  }'
# → 200 {"answer": "...", "citations": [...], "answer_id": "..."}

Or get just the matching passages and run your own LLM:

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": 5
  }'
# → 200 {"results": [...], "count": 5}

5 — (Optional) Receive webhooks

Instead of polling, have RAVEN POST you a signed event when an ingest job or async batch reaches a terminal state. Webhook registration is operator-managed (admin-only) — ask an operator to register your receiver URL and the events you want. See Building blocks → Webhooks for the signature scheme.

Each row is a self-contained capability. Use one, several, or all of them.

Batch chat — sync and async

Send up to 50 questions in one call. By default the call blocks and returns every answer inline. For large batches that would outlast your load balancer's idle timeout, set "async_": true (or add ?async=true): RAVEN returns 202 + a batch_id immediately, drains the batch in the background, and you poll GET /v1/answer/batch/{batch_id} (or subscribe a webhook).

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

Streaming

Add "stream": true to a /v1/chat body. The response is text/event-stream (Server-Sent Events) carrying token / tool_call / tool_result / done frames as they happen. Auth and scope are still checked before the first byte, and the final frame still includes an answer_id for the audit trail.

Personas (Domain Knowledge) & response formats

Pass domain_knowledge_id on any /v1/chat or /v1/chat/batch call to apply a tenant-authored system prompt, tool allowlist, and default output format on top of RAVEN's safety rules. Pass response_format ({"style": "narrative" | "terse" | "json", "schema": {...}}) to pin the output shape for one call. An unknown or cross-tenant domain_knowledge_id returns 404 domain_knowledge_not_found; if omitted, your tenant+app default persona applies, else RAVEN's built-in prompt. Manage personas in the Personas tab or via /v1/domain-knowledges. Full design: docs/RAVEN-DOMAIN-KNOWLEDGE-DESIGN.md.

Webhooks

When a webhook is registered for your namespace, RAVEN POSTs a JSON event to your URL on terminal status. Each delivery carries two headers:

X-Raven-Signature: sha256=<hex HMAC-SHA256(secret, "{timestamp}." + body)>
X-Raven-Timestamp: <unix epoch seconds>

To verify: reject if X-Raven-Timestamp is more than ~5 minutes (300s) off your clock, recompute the HMAC over "{timestamp}." + rawBody with your webhook secret, and compare constant-time against the digest. Event type strings:

The payload body is {"webhook_id": ..., "event": {"type": ..., "occurred_at": ..., "job": {...}}}. The job/batch summary is lean — fetch full detail via GET /v1/jobs/{id} or GET /v1/answer/batch/{id}.

Self-service namespace management

Your namespace-scoped key can manage its own namespace through a subset of the /v1/admin/* routes — no global admin key needed. Acting on a namespace your key doesn't cover returns 403 namespace_forbidden.

Destructive teardown (namespace / application delete) requires the header X-Confirm-Destroy: yes. Add ?delete_source_files=true to also remove S3 files from RAVEN-owned buckets, or ?purge_history=true for GDPR-style erasure of stored prompts. Webhook and API-key CRUD remain admin-only.

Every request needs the X-API-Key header. Optionally add X-Actor-User-Id — an opaque label identifying which of your end users triggered the call. RAVEN never authorizes on it; it's stamped on the audit row for your own traceability.

Structured error envelope

Every 4xx/5xx response (published in the OpenAPI spec) comes back in one shape so you can codegen typed error handling:

{
  "error_code": "namespace_forbidden",   // machine-readable, snake_case
  "message": "tenant 'x' is not authorised for namespace 'y'",
  "retryable": false,                     // true → safe to retry
  "request_id": "req_...",                // mirrors X-Request-ID; share with operators
  "service": null,                        // upstream that caused it, when relevant
  "stage": null,                          // ingest stage, when relevant
  "details": null                         // curated, client-safe context
}

429 and 503 responses also carry a Retry-After header. Graceful degradation (e.g. a reranker fallback) is reported on a successful response via a top-level {"degraded": true, "warnings": [...]} envelope plus a Warning: 299 header — not an error.

Querying a namespace with nothing indexed yet

Common error codes

Every error includes a request_id. Share it with an operator and they can grep the structured log for the full server-side trace.