> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ragrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API Quickstart

> Build a knowledge base and chat over HTTP.

## 1. Install and Run

```bash theme={null}
pip install "ragrails[server-qdrant]"
export VOYAGE_API_KEY="..."
export OPENAI_API_KEY="..."
docker run -p 6333:6333 qdrant/qdrant
ragrails-api
```

The API starts on `http://127.0.0.1:8000`. Open `http://127.0.0.1:8000/docs` for Swagger UI.

REST defaults live in request payloads. These examples pass the vector database, embedding model, and LLM model explicitly.

## 2. Ingest

`POST /v1/pipelines/ingest` extracts, chunks, embeds, and stores content.

```bash theme={null}
curl -X POST http://127.0.0.1:8000/v1/pipelines/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Refund policy\n\nCustomers can request a refund within 30 days of purchase. Refunds are returned to the original payment method within 5 business days.",
    "embedding": {"provider": "voyage", "model": "voyage-3"},
    "storage": {"vector_db": "qdrant", "collection": "support", "url": "http://localhost:6333"}
  }'
```

## 3. Query

`POST /v1/pipelines/query` embeds the question and retrieves matching chunks.

```bash theme={null}
curl -X POST http://127.0.0.1:8000/v1/pipelines/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How long do I have to request a refund?",
    "embedding": {"provider": "voyage", "model": "voyage-3"},
    "retrieval": {"vector_db": "qdrant", "collection": "support", "url": "http://localhost:6333", "top_k": 5}
  }'
```

## 4. Chat

`POST /v1/chat` retrieves context and asks the configured LLM for an answer.

```bash theme={null}
curl -X POST http://127.0.0.1:8000/v1/chat \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How long do I have to request a refund?",
    "llm_provider": "openai",
    "llm_model": "gpt-4o-mini",
    "embedder_provider": "voyage",
    "embedder_model": "voyage-3",
    "vector_db": "qdrant",
    "collection": "support",
    "url": "http://localhost:6333",
    "history": []
  }'
```

Pass the returned `history` array back on the next chat request to keep conversation context.

## 5. Stream Chat

```bash theme={null}
curl -N -X POST http://127.0.0.1:8000/v1/chat/stream \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How long do I have to request a refund?",
    "llm_provider": "openai",
    "llm_model": "gpt-4o-mini",
    "embedder_provider": "voyage",
    "embedder_model": "voyage-3",
    "vector_db": "qdrant",
    "collection": "support",
    "url": "http://localhost:6333"
  }'
```

Next, use [REST Ingest](/usage/server/ingest) for full ingest options, [REST Query](/usage/server/query) for retrieval options, or [Pipeline Overview](/usage/server/pipeline-overview) to run each stage separately.