Rag.NET.Api 1.0.0

Rag.NET.Api

ASP.NET Core REST endpoints for a Rag.NET pipeline: MapRagNetApi() exposes ingest, retrieve, ask and delete over HTTP with API-key authentication, and MapRagNetWebhooks() adds an HMAC-verified ingestion webhook.

Install

dotnet add package Rag.NET.Api

Setup

using Rag.NET.Api.DependencyInjection;
using Rag.NET.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRagNet();  // configure your pipeline as usual
builder.Services.AddRagNetApi(o => o.ApiKeys = ["your-api-key"]);

var app = builder.Build();

app.UseRagNetApiAuthentication(); // X-Api-Key middleware
app.MapRagNetApi();

app.Run();

Authentication is an explicit decision: AddRagNetApi throws at startup when RagApiOptions.ApiKeys is empty, unless you opt out deliberately with o.AllowAnonymous = true (for example behind a trusted gateway that authenticates upstream). Setting both at once is rejected as a contradiction. The middleware also fails closed at request time — if the options end up with no keys and no opt-out, requests get 401 rather than an accidentally open API.

Deciding it is not the same as applying it, so both calls above are required, in that order. MapRagNetApi() throws at startup if AddRagNetApi was never called, and — unless you set AllowAnonymous — if app.UseRagNetApiAuthentication() has not already put the middleware in the pipeline. Either omission used to map the endpoints anyway and serve every one of them to every caller, with the configured keys sitting unread.

Example

Event-driven ingestion via the webhook endpoint — callers authenticate with an HMAC-SHA256 signature over the raw request body instead of the API key:

builder.Services.AddRagNetWebhooks(o =>
{
    o.Secret = builder.Configuration["Webhooks:Secret"]!; // required, non-empty
});

app.UseRagNetApiAuthentication();
app.MapRagNetWebhooks(); // POST /rag/webhooks/ingest

The webhook route prefix is exempted from API-key auth (the HMAC signature replaces the key). MapRagNetApi() refuses to start if that exemption would also cover any of the API's own routes — a WebhookOptions.RoutePrefix such as "/rag" that is a parent of /rag/ingest throws at mapping time instead of silently disabling authentication.

curl -X POST https://localhost:5001/rag/webhooks/ingest \
  -H "X-Signature-256: sha256=<hex hmac of body>" \
  -d '{"documentId":"doc-1","content":"full document text"}'

Full guide

• Event-driven ingestion
• MCP and API hosting patterns