Serving an HTTP API¶
ragpick serve exposes any config (a pipeline or a router) as a JSON API.
ragpick serve -c rag.yaml # http://127.0.0.1:8000
ragpick serve -c router.yaml --host 0.0.0.0 --port 8080
It runs on uvicorn when installed (pip install uvicorn, recommended for
production) and falls back to Python's built-in threaded HTTP server otherwise. The
application is a plain ASGI app, so you can also mount it in your own server:
from ragpick import load_engine
from ragpick.server import App, asgi_app
application = asgi_app(App(load_engine("rag.yaml"))) # uvicorn module:application
Endpoints¶
| Method & path | Body | Returns |
|---|---|---|
GET /health |
– | {"status": "ok" \| "not_ready", "version"}, 503 until ingested. No auth. |
GET /info |
– | name, blueprint, version, routes (for routers) |
POST /query |
{"question", "groups"?, "filters"?, "top_k"?, "trace"?} |
{"text", "citations", "route", "contexts", "usage", "trace"?} |
POST /retrieve |
same | {"contexts": [...]} (no generation) |
POST /chat |
{"message", "session_id"?, "groups"?, "tenant"?, "stream"?} |
answer + session_id, standalone_question (Conversations) |
DELETE /sessions/{id} |
– | forget a chat session (owner only) |
POST /feedback |
{"answer_id", "rating", "comment"?} |
rate an answer this key received (Feedback) |
curl -s localhost:8000/query \
-H "Authorization: Bearer $PORTAL_KEY" \
-d '{"question": "How do I reset my password?"}'
Add "stream": true to get server-sent events instead of one JSON body: one
contexts event, many delta events ({"text": "..."}), then a final answer event
(the same JSON as a normal response). Retrieval errors still return a normal error
status, because retrieval runs before the stream starts. A provider failure mid-stream
ends the stream with an error event.
curl -N localhost:8000/query -d '{"question": "How do I reset my password?", "stream": true}'
Each context is {"id", "doc_id", "score", "source", "text", "metadata"}. Errors are
{"error": "..."} with a meaningful status: 401/403 auth, 404, 405, 413 body too large,
422 invalid body, 502 model provider failed, 503 not ingested. Provider and
configuration details are logged on the server, not returned to clients.
Authentication and groups¶
serve:
host: 0.0.0.0
port: 8000
api_keys:
- {key: "${PORTAL_KEY}", name: support-portal, groups: [support]}
- {key: "${HR_APP_KEY}", name: hr-app, groups: [hr, support]}
- {key: "${ADMIN_KEY}", name: admin} # groups: null → may act as any groups
cors_origins: ["https://portal.example.com"]
allow_traces: false
max_body_bytes: 65536
- With
api_keysset, every endpoint except/healthrequiresAuthorization: Bearer <key>(compared in constant time). - The key decides the groups. A request that omits
groupsacts as all of its key's groups; a request may narrow them ("groups": []is public-only) but can't add a group its key doesn't have (403). This is what makes document- and table-level access control safe over HTTP. - Without
api_keys, requestgroupsare trusted as sent. That's fine on localhost or behind your own authenticated backend;ragpick servewarns when binding a public interface without keys. - Keep keys in environment variables (
${PORTAL_KEY}); they are never written to disk.
Tenants¶
With tenancy enabled, requests carry "tenant": "acme", or the API key fixes it
(api_keys[].tenant); see Multi-tenancy.
Operations¶
- Traces in responses are off unless
serve.allow_traces: true. Server-side tracing (tracing.enabled, JSONL/OpenTelemetry exporters) works independently. - Turn on
cacheto make repeated questions instant and free. - One process loads the index into memory; for more throughput run several uvicorn workers behind a load balancer, with a shared vector database such as Qdrant.