Integrating Egret into Your Application in 15 Minutes

Egret's REST API is straightforward to integrate. This guide goes from zero to a working streaming query in a single sitting. All examples use curl and vanilla JavaScript — no SDKs required.

1. Get an API key

Sign up at getegret.com, then go to Settings → API Keys → New Key. Copy the full key — it's only shown once. Your key will look like egret_tX1g3XB143QVaf....

All API requests use this key in the Authorization header:

Authorization: Bearer egret_tX1g3XB143QVaf...

2. Explore available domains

Domains are public — no auth needed to browse them:

curl https://api.getegret.com/v1/domains/

Each domain has categories representing jurisdictions. For Business Continuity:

curl https://api.getegret.com/v1/domains/business-continuity/categories/

This returns available categories — currently us (United States) and sg (Singapore).

3. Make your first query

curl -X POST https://api.getegret.com/v1/query/ \
  -H "Authorization: Bearer egret_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the board responsibilities for BCM governance under FFIEC?",
    "domain": "business-continuity",
    "category": "us",
    "mode": "compliance"
  }'

The response includes response (the full answer), sources[] (cited documents with excerpts and download URLs), suggestions[] (related follow-up questions), and session_id for continuing the conversation.

4. Continue a conversation

Pass session_id back in subsequent queries to maintain context across turns:

{
  "query": "What about audit responsibilities specifically?",
  "domain": "business-continuity",
  "category": "us",
  "mode": "compliance",
  "session_id": "6143159f-ef21-4a1f-97f1-ee9cb7ac3f08"
}

5. Add streaming

Set "stream": true and switch to a fetch + ReadableStream approach. The response is newline-delimited JSON. Three event types arrive in order: sources (retrieved documents, before generation starts), text_delta (one per token chunk), and done (final metadata including token usage and the assembled full text).

const response = await fetch("https://api.getegret.com/v1/query/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer egret_...",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    query: "What are the board responsibilities for BCM governance?",
    domain: "business-continuity",
    category: "us",
    mode: "compliance",
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split("\n");
  buffer = lines.pop();

  for (const line of lines) {
    if (!line.trim()) continue;
    const event = JSON.parse(line);

    if (event.type === "sources") {
      console.log("Sources:", event.sources.length, "chunks retrieved");
    } else if (event.type === "text_delta") {
      process.stdout.write(event.text);
    } else if (event.type === "done") {
      console.log("\nTokens used:", event.input_tokens + event.output_tokens);
    }
  }
}

6. Upload to your private knowledge base

To blend your organisation's internal documents into responses, upload them via the dashboard (Organisation → Knowledge Base → Upload). Supported formats: PDF (text-based), DOCX, XLSX, CSV, and Markdown. Once uploaded and indexed, your documents are automatically included in retrieval alongside Egret's regulatory library. Sources from your private KB are flagged with is_private: true in the response.

What's next

The full API reference — including session management, organisation settings, and billing endpoints — is in the documentation. If you run into anything, reach out at support@getegret.com.