REST API Quickstart

1. Install and Run

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 JSON-addressable content. Use POST /v1/pipelines/ingest/mixed when browser uploads must be indexed in the same request as paths, folders, URLs, APIs, or Markdown.

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.

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.

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

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 for full ingest options, REST Query for retrieval options, or Pipeline Overview to run each stage separately.

Get Started

Workflows

Pipeline

Maintenance