> ## 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.

# Run the REST API

> Expose Ragrails workflows over HTTP.

Use this walkthrough when another service, frontend, worker, or non-Python client needs to call Ragrails over HTTP.

## What you will run

A FastAPI server with endpoints for ingestion, chunking, embedding, storage, retrieval, pipelines, chat, and streaming.

## 1. Install server extras

Choose the vector database stack you need:

```bash theme={null}
pip install "ragrails[server-qdrant]"
# or: pip install "ragrails[server-pinecone]"
# or: pip install "ragrails[server-weaviate]"
```

Set provider credentials before starting the server:

```bash theme={null}
export VOYAGE_API_KEY="..."
export OPENAI_API_KEY="..."
```

## 2. Start the server

```bash REST API theme={null}
ragrails-api --host 127.0.0.1 --port 8000
```

For local development:

```bash REST API theme={null}
ragrails-api --reload
```

The server listens on `http://127.0.0.1:8000` by default.

| Resource       | URL                    |
| -------------- | ---------------------- |
| Health check   | `GET /v1/health`       |
| Swagger UI     | `GET /docs`            |
| OpenAPI schema | `GET /v1/openapi.json` |

## 3. Smoke test

```bash theme={null}
curl http://127.0.0.1:8000/v1/health
```

Then run a small pipeline request:

```bash theme={null}
curl -X POST http://127.0.0.1:8000/v1/pipelines/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What does this knowledge base cover?",
    "retrieval": {
      "vector_db": "qdrant",
      "collection": "docs",
      "url": "http://localhost:6333",
      "top_k": 5
    }
  }'
```

## Common endpoints

| Need                        | Endpoint                                   |
| --------------------------- | ------------------------------------------ |
| Scrape URLs                 | `POST /v1/ingest/url`                      |
| Stream URL scraping         | `POST /v1/ingest/url/stream`               |
| Parse server-side files     | `POST /v1/ingest/docs`                     |
| Upload files                | `POST /v1/ingest/docs/upload`              |
| Fetch REST APIs             | `POST /v1/ingest/api`                      |
| Run full ingest pipeline    | `POST /v1/pipelines/ingest`                |
| Run query pipeline          | `POST /v1/pipelines/query`                 |
| Retrieve chunks             | `POST /v1/retrieve`                        |
| Chat                        | `POST /v1/chat`                            |
| Stream chat                 | `POST /v1/chat/stream`                     |
| Store, edit, delete vectors | `POST /v1/store`, `/v1/edit`, `/v1/delete` |

## Production checklist

* Put the service behind your auth layer, gateway, and rate limits.
* Use managed vector storage or persistent volumes for production indexes.
* Keep API keys in environment variables or your secret manager.
* Generate typed clients from `/v1/openapi.json`.
* Prefer streaming endpoints for long crawls and responsive chat UIs.
* Add request logging and audit logging around ingestion, chat, and tool-using workflows.

## Next steps

* [REST API overview](/usage/server/overview)
* [REST API reference](/reference/rest-api)
* [Streaming](/capabilities/streaming)
* [Website walkthrough](/guides/website-to-rag)