EgretAI
Log inGet Started Free

Sessions

Sessions group related queries into conversations, maintaining context across multiple questions. Each session is scoped to a domain and category, and retains the message history so the model can reference prior exchanges.

How sessions are created

Sessions are created automatically on your first query. The query response includes a session_id — pass this in subsequent requests to continue the conversation in context.

{
  "query": "What are the RTO requirements under FFIEC?",
  "domain": "business-continuity",
  "category": "us",
  "mode": "compliance",
  "session_id": "53c719f0-4520-45e7-8406-3074c40bf9ce"
}

List recent sessions

GET https://api.getegret.com/v1/sessions/recent/?limit=5
Authorization: Bearer egret_...

The limit query parameter controls how many sessions are returned. Response:

[
  {
    "session_id": "53c719f0-4520-45e7-8406-3074c40bf9ce",
    "title": "What Business Continuity Management according to FFIEC Information Technology Examination Handbook?",
    "domain_slug": "business-continuity",
    "domain_name": "Business Continuity",
    "category_name": "United States",
    "category_code": "us",
    "created_at": "2026-03-25T19:52:47.347245Z",
    "last_activity_at": "2026-03-25T19:53:02.763901Z",
    "message_count": 2
  }
]

List messages in a session

GET https://api.getegret.com/v1/sessions/{session_id}/messages/
Authorization: Bearer egret_...

Returns the full message history for a session. Each message has a sender of either user or assistant:

[
  {
    "session_id": "b561cfc9-0c52-4272-993e-3a12167267cd",
    "sender": "user",
    "content": "Explain the BCI-BCM lifecycle",
    "bedrock_model_id": "us.anthropic.claude-3-5-haiku-20241022-v1:0",
    "sources": [],
    "input_tokens": 0,
    "output_tokens": 0,
    "created_at": "2026-03-18T22:22:39.918153Z",
    "context_quality": null
  },
  {
    "session_id": "b561cfc9-0c52-4272-993e-3a12167267cd",
    "sender": "assistant",
    "content": "# Business Continuity Management (BCM) Lifecycle...",
    "bedrock_model_id": "us.anthropic.claude-3-5-haiku-20241022-v1:0",
    "sources": [
      {
        "filename": "EXPLAINED-business-continuity-management.pdf",
        "page_number": 10,
        "excerpt": "The BCI BCM Lifecycle outlines the activities that an organisation must undertake...",
        "score": 0.6082978,
        "relevance": "Relevant",
        "source_type": "document",
        "download_url": "https://egret-docs.s3.amazonaws.com/...",
        "is_private": true
      }
    ],
    "input_tokens": 5607,
    "output_tokens": 664,
    "created_at": "2026-03-18T22:22:39.922604Z",
    "context_quality": {
      "chunks_retrieved": 7,
      "avg_relevance_score": 0.5552,
      "insufficient_context": false
    }
  }
]

The is_private flag on each source indicates whether the passage came from your organisation's private knowledge base (true) or Egret's public regulatory library (false).

Rename a session

POST https://api.getegret.com/v1/sessions/{session_id}/rename/
Authorization: Bearer egret_...
Content-Type: application/json

{
  "title": "Renamed Title"
}

Response:

{
  "session_id": "b561cfc9-0c52-4272-993e-3a12167267cd",
  "title": "Renamed Title"
}

Delete a session

DELETE https://api.getegret.com/v1/sessions/{session_id}/delete/
Authorization: Bearer egret_...

Returns 204 No Content:

{
  "detail": "Chat session deleted."
}

Next steps