Add an HTTP API to Microsoft GraphRAG with FastAPI

Microsoft GraphRAG ships a CLI and Python API, but not a production HTTP service. To expose it over HTTP, load one fixed GraphRAG project, keep its index tables in memory for queries, and run expensive indexing as a controlled background job. Do not accept an arbitrary filesystem path from each request.

This guide uses GraphRAG's current graphrag.api interface with FastAPI. It provides three endpoints:

• POST /index starts an index build and returns immediately.

• GET /index/status reports the current job state.

• POST /query runs a global search against the latest loaded index.

1. Create and Initialize the Project

GraphRAG currently requires Python 3.10–3.12. Create a virtual environment and install the dependencies:

Create a GraphRAG workspace:

Add your provider configuration to rag/settings.yaml and the required secret to rag/.env. Put source documents in rag/input/, then build the first index:

The official GraphRAG quickstart explains model configuration and warns that indexing can consume substantial LLM resources. Start with a small dataset.

2. Add the FastAPI Service

Create api.py beside the rag directory:

This example fixes the GraphRAG project root in server configuration. That avoids a path-traversal bug in which a caller could ask the service to index or read an arbitrary server directory.

3. Run the API

Start Uvicorn from the directory containing api.py:

Keep it bound to 127.0.0.1 during development. If another service or user must reach it, add an authenticated proxy instead of exposing the development server directly.

4. Start and Monitor Indexing

Start a rebuild:

Check its state:

A successful run reloads the Parquet tables so later queries use the new index. The process keeps the previous in-memory tables available while a rebuild runs.

5. Query GraphRAG

Send a JSON request rather than putting the question in a URL:

The example uses global search. GraphRAG also offers local, DRIFT, and basic query methods; choose the method that matches the question and load the tables required by that API.

Production Checklist

Before deploying this service:

1. Add authentication and authorization to every endpoint.

2. Move indexing to a durable job queue if the process may restart or you need more than one worker.

3. Store job state outside process memory.

4. Limit request size, query length, concurrency, and model spend.

5. Separate read traffic from index writes and switch index versions atomically.

6. Redact secrets and sensitive document text from logs.

7. Pin and test the GraphRAG version; its configuration and APIs can change between releases.

An HTTP endpoint is only the service boundary. If AI clients need portable discovery and tool schemas, read MCP vs API before deciding whether to expose the same operation through MCP as well.

Sources

• Microsoft GraphRAG quickstart

• Microsoft GraphRAG CLI reference

• Microsoft GraphRAG Python API overview

• FastAPI documentation