Queries & RAG

The query endpoint is the core of Egret. Send a natural-language question, and Egret retrieves relevant passages and generates a cited answer.

Making a query

POST /api/v1/rag/query/
Content-Type: application/json
Authorization: Api-Key ek_live_...

{
  "query": "What are the breach notification requirements?",
  "domain": "hipaa",
  "session_id": "optional-session-uuid",
  "model_tier": "standard"
}

Response format

{
  "id": "q_abc123",
  "answer": "Under HIPAA, covered entities must notify...",
  "citations": [
    {
      "document": "hipaa-breach-notification.pdf",
      "section": "§ 164.404",
      "text": "A covered entity shall, following the discovery...",
      "relevance_score": 0.94
    }
  ],
  "credits_used": 1,
  "model_tier": "standard",
  "session_id": "sess_xyz789"
}

Parameters

Parameter	Type	Required	Description
`query`	string	Yes	The natural-language question
`domain`	string	Yes	Domain slug or ID
`session_id`	string	No	Continue an existing session for context
`model_tier`	string	No	`standard` (default) or `advanced`
`max_citations`	integer	No	Maximum citations to return (default: 5)

Citation format

Each citation includes the source document name, section reference, extracted text, and a relevance score between 0 and 1.