Queries & RAG
The query endpoint is the core of Egret. Send a natural-language compliance question, and Egret searches both the curated regulatory library and your organisation's private documents, then generates a cited answer grounded in real sources.
Make a query
POST https://api.getegret.com/v1/query/
Authorization: Bearer egret_...
Content-Type: application/json
{
"query": "What is Business Continuity Management according to the FFIEC IT Examination Handbook?",
"domain": "business-continuity",
"category": "us",
"mode": "compliance",
"model": "us.anthropic.claude-3-5-haiku-20241022-v1:0",
"knowledge_scope": "public",
"stream": false
}Request parameters
| Field | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Your compliance question in plain language |
domain | string | Yes | Domain slug (e.g. business-continuity). See Domains. |
category | string | Yes | Category code (e.g. us, sg). See Domains → List categories. |
mode | string | Yes | Controls how the answer is generated.compliance — prioritises accuracy and maximum source citation, best for regulatory research.advisory — generates more interpretive, guidance-oriented responses.auto — automatically classifies your question and routes it to the appropriate mode. |
model_id | string | No | Model to use. Omit to use the current default model. See Available models. |
stream | boolean | No | Set true to receive a Server-Sent Events stream. Default: false. See Streaming. |
session_id | string | No | Pass the session_id from a previous response to continue a conversation with context. |
knowledge_scope | string | No | Filter knowledge sources: all (default — public + private), public (regulatory library only), private (your organisation's documents only). Requires an org with an active knowledge base for private. |
Response
{
"response": "# Business Continuity Management (BCM)\n\nBCM is the process for management to oversee and implement resilience, continuity, and response capabilities...",
"sources": [
{
"uri": "s3://egret-docs/business-continuity/pdf/us/ffiec_itbooklet_businesscontinuitymanagement_v3.pdf",
"filename": "ffiec_itbooklet_businesscontinuitymanagement_v3.pdf",
"page_number": null,
"excerpt": "BCM is the process for management to oversee and implement resilience, continuity, and response capabilities to safeguard employees, customers, and products and services.",
"score": 0.8438505,
"download_url": "https://egret-docs.s3.amazonaws.com/..."
}
],
"suggestions": [
"What are the key differences between Business Continuity Planning and Business Continuity Management?",
"How do organizations develop a comprehensive BCM strategy?",
"What role does the board of directors play in BCM?"
],
"context_quality": {
"insufficient_context": false,
"chunks_retrieved": 5,
"avg_relevance_score": 0.815
},
"usage": {
"input_tokens": 9042,
"output_tokens": 597,
"cost_usd": 0.0030067,
"model": "us.anthropic.claude-3-5-haiku-20241022-v1:0"
},
"performance": {
"retrieval_latency_ms": 2003,
"generation_latency_ms": 12986,
"total_latency_ms": 15111,
"chunks_retrieved": 5,
"avg_relevance_score": 0.815
},
"session_id": "53c719f0-4520-45e7-8406-3074c40bf9ce",
"message_id": 120
}Response fields
| Field | Description |
|---|---|
response | The generated answer in Markdown format, with inline source references (e.g. [Source 1]) |
sources | Array of retrieved document passages. Each entry includes filename, excerpt, relevance score, relevance label, source_type, and a pre-signed download_url to the source PDF |
sources[].relevance | "Highly Relevant", "Relevant", or "Partially Relevant" — human-readable relevance label |
sources[].source_type | "document" (Phase B: "web") — the type of knowledge source |
suggestions | Follow-up questions suggested by the model based on the retrieved context |
context_quality | Retrieval diagnostics — insufficient_context: true means the knowledge base did not contain enough relevant material to answer confidently |
usage | Token counts, cost in USD, and the model used |
performance | Latency breakdown for retrieval and generation |
session_id | Pass this value as session_id in your next request to continue the conversation with context |
message_id | Unique identifier for this specific message within the session |
Available models
The list of available models changes as new models are added. Always fetch the current list from the API rather than hard-coding a model ID:
GET https://api.getegret.com/v1/models/
Authorization: Bearer egret_...Each model entry includes its model_id, name, tier, credit_cost, supports_streaming, and an is_default flag. Pass the model_id value in your query request. Omit model_id entirely to use whichever model has is_default: true.
See Billing for how credit costs map to your plan.