API Documentation: Parrot Chat Endpoint

Endpoint URL

https://calvinistparrot.com/api/parrot-chat

Overview

The Parrot Chat endpoint provides real-time conversational interactions by streaming responses. It handles creating chat sessions, processing user messages, maintaining context, and integrating multiple theological agents including a final review stage ("Calvin's Review").

Important: The API now includes an intelligent memory extraction system that learns from conversations to provide personalized pastoral care. The userId is required for this feature to work properly—it enables the system to build a profile of each user's spiritual journey, theological questions, and ministry context over time.

As with the Parrot QA API, the Parrot Chat endpoint supports multiple denominational modes to cater to various theological traditions. However, we will not compromise on the following essential doctrines:

• The Trinity: One God, eternally existing in three persons—Father, Son, and Holy Spirit.
• The Character of God: God is holy, supreme, sovereign, immutable, faithful, good, patient, gracious, merciful, loving, and just; His wrath against sin is real.
• The Authority of Scripture: The Bible is the inspired, inerrant, and infallible Word of God, serving as the ultimate authority in all matters of faith and practice.
• The Deity and Humanity of Christ: Jesus Christ is truly God and truly man (Vera Deus, vera homo).
• The Incarnation and Virgin Birth: Jesus Christ took on human nature through miraculous conception by the Holy Spirit and was born of the Virgin Mary.
• The Atonement (Christ's Saving Work): Christ's sacrificial death on the cross is necessary and sufficient to reconcile sinners to God.
• The Gospel: Salvation is secured by Christ's historical death, burial, and resurrection on the third day, demonstrating His victory over sin and death.
• Justification by Faith: Individuals are justified solely by grace alone through faith alone in Christ alone, apart from works.
• The Resurrection: Christ's bodily resurrection, confirming His divinity and victory over sin and death.
• Christ's Return and Final Judgment: Jesus Christ will return personally and bodily to judge the living and the dead, culminating in the renewal of all things.

QA Endpoint

For simplicity, I created this other endpoint that focuses on quick QA. Please check the Parrot QA API documentation for more information.

---

How It Works

1. Chat Session Initialization

   • There are two ways to start a new chat:
   • From Parrot QA: Initialize with both question and answer
   • From Chat Interface: Initialize with just a question

2. Chat Continuation

   • Uses stored chat history to maintain context
   • Processes messages through multiple agents and tools
   • Streams real-time responses with progress updates

3. Memory Extraction & Personalization

   • Automatic Learning: After each conversation, the system extracts and updates user memories in the background
   • Pastoral Context: Builds a profile including spiritual maturity, ministry context, theological preferences, and question history
   • Smart Responses: Future conversations are informed by this context for more personalized, pastorally-appropriate answers
   • Privacy: Memory data is tied to userId and never exposed to other users
   • No Interruption: Memory extraction happens asynchronously and doesn't block responses

4. Denomination Handling

   • User's denomination preference is stored in their profile and automatically applied
   • Each denomination maps to a specific system prompt
   • Affects how the AI interprets and responds to questions
   • Maintains core doctrinal consistency while respecting denominational distinctives

Why userId is Critical

The userId parameter enables:

• Memory persistence across conversations
• Spiritual journey tracking (seeker → new believer → mature believer progression)
• Personalized depth (concise vs. detailed responses based on learned preferences)
• Gospel presentation tracking (avoids redundant salvation explanations)
• Ministry context awareness (tailors examples to user's roles)
• Doctrinal question history (identifies areas needing more teaching)

Without a userId, the system cannot learn or personalize—each conversation becomes isolated and generic.## API Reference

Request Structure

Send a JSON payload with these possible fields:

• userId (string, REQUIRED): Unique identifier for the user. Critical for memory extraction and personalization. Without this, the system cannot learn user preferences or provide pastoral continuity across conversations.
• chatId (string, optional): Identifier for an existing chat session.
• message (string): The user's chat message.
• initialQuestion (string, optional): For starting a new chat session.
• initialAnswer (string, optional): Initial answer for a new chat session.
• denomination (string, optional): The theological perspective. Note: This parameter is now primarily stored in the user's profile. If provided, it will be used as a fallback when no profile denomination exists. Possible values:
  • reformed-baptist (Reformed Baptist perspective - default)
  • presbyterian (Presbyterian perspective)
  • wesleyan (Wesleyan perspective)
  • lutheran (Lutheran perspective)
  • anglican (Anglican perspective)
  • pentecostal (Pentecostal/Charismatic perspective)
  • non-denom (Non-Denominational Evangelical perspective)
• isAutoTrigger (boolean, optional): Indicates if the message is auto-triggered (for conversation continuity).
• clientChatId (string, optional): Client-provided chatId for optimistic UI updates. If provided when creating a new chat, this ID will be used instead of a server-generated one.

Response Stream Format

The API streams different event types as JSON objects:

1. Progress Updates - Status messages during processing

{"type": "progress", "title": "Looking for articles", "content": "Searching for: predestination"}

2. Parrot Messages - Main response content (streamed in chunks)

{"type": "parrot", "content": "The doctrine of predestination..."}

3. Tool Progress - Ephemeral status messages during tool execution (not persisted)

{"type": "tool_progress", "toolName": "supplementalArticleSearch", "message": "Searching for articles on predestination..."}

4. Tool Summary - Persistent tool results (saved to database)

{"type": "tool_summary", "toolName": "supplementalArticleSearch", "content": "Found 3 relevant articles..."}

5. Reference Materials - Related articles from GotQuestions and Monergism

{"type": "gotQuestions", "content": "- [What is predestination?](https://www.gotquestions.org/predestination.html) _(GotQuestions)_"}

6. CCEL Results - Christian Classics Ethereal Library sources

{"type": "CCEL", "content": "- [Calvin's Institutes, Book III](https://ccel.org/...)"}

7. Conversation Name Updated - Sent when the conversation name is generated (for sidebar updates)

{"type": "conversationNameUpdated", "chatId": "chat123", "name": "Understanding Predestination"}

8. Stream Completion

{"type": "done"}

Memory Extraction (Background Process)

After the response stream completes, the system automatically extracts and updates user memories in a background process (non-blocking). This includes:

Extracted Information:

• Spiritual status (seeker, new believer, growing believer, mature believer)
• Ministry context (teacher, elder, small group leader, etc.)
• Church involvement level
• Preferred answer depth (concise, moderate, detailed)
• Follow-up tendency (high, moderate, low)
• Gospel presentation count
• Doctrinal question categories (core, secondary, tertiary)

How it Works:

1. After Parrot's response is sent, the conversation history is analyzed
2. An LLM extracts structured insights using a JSON schema
3. Memories are stored in a LangGraph MemoryStore (key-value pairs)
4. User profile counters are updated (question types, Gospel presentations)
5. Future conversations inject this context into the system prompt for personalized responses

Developer Notes:

• Memory extraction never blocks the response stream
• Errors in memory extraction are logged but don't affect user experience
• Memory data is scoped to userId only
• The system uses conservative updates (won't overwrite established preferences with weak signals)

Usage Patterns

1. Initialize from Parrot QA

POST /api/parrot-chat
{
  "userId": "user123",
  "initialQuestion": "What is predestination?",
  "initialAnswer": "Predestination refers to...",
  "denomination": "reformed-baptist"
}

2. Initialize from Chat Interface

POST /api/parrot-chat
{
  "userId": "user123",
  "initialQuestion": "What is predestination?"
}

Response:

{
  "chatId": "chat123"
}

Note: This endpoint only returns the chatId. The client should navigate to a new URL with this chatId (e.g., /chat123). When the chat page loads, it will automatically trigger the streaming process using the isAutoTrigger flag to process the initial question.

Complete Flow Example

1. Start a new chat and get the chatId:

// In /page.tsx
const handleStartNewChat = async () => {
  const response = await fetch('/api/parrot-chat', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({ 
    userId: "user123", 
    initialQuestion: "What is predestination?" 
   }),
  });
  const { chatId } = await response.json();
  router.push(`/${chatId}`);  // Navigate to chat page
};

2. Chat page loads and auto-triggers the initial question:

// In /[chatId]/page.tsx
useEffect(() => {
  // When we detect only a user message with no response yet
  if (messages.length === 1 && messages[0].sender === "user" && !autoSentRef.current) {
   autoSentRef.current = true;
   // Auto-trigger the API call with the isAutoTrigger flag
   handleSendMessage({ 
    message: messages[0].content, 
    isAutoTrigger: true 
   });
  }
}, [messages, handleSendMessage]);

// Actual API call with isAutoTrigger flag
const handleSendMessage = async ({ message, isAutoTrigger }) => {
  const response = await fetch("/api/parrot-chat", {
   method: "POST",
   headers: { "Content-Type": "application/json" },
   body: JSON.stringify({
    chatId: "chat123",  // From URL params
    message: "What is predestination?",  // Initial question
    isAutoTrigger: true  // This tells the API not to store the message again
   }),
  });
  
  // Handle streaming response...
};

3. API processes the request differently with isAutoTrigger:

• When isAutoTrigger: true, the API doesn't save the message again (it's already stored)
• The API processes the message and streams the response
• The client receives and displays the streaming response

3. Continue Conversation

POST /api/parrot-chat
{
  "userId": "user123",
  "chatId": "chat123",
  "message": "How does it relate to free will?"
}

4. Fetch Chat History

GET /api/parrot-chat?chatId=chat123

Response:

{
  "chat": {
   "id": "cm7p6rik1001emqp0slgxgu1j",
   "userId": "6754db6b00119ba9e0da",
   "conversationName": "Understanding Predestination",
   "denomination": "reformed-baptist",
   "createdAt": "2025-02-28T19:48:22.321Z",
   "modifiedAt": "2025-02-28T19:48:45.855Z"
  },
  "messages": [
   {
    "id": "cm7p6rimi001gmqp0liuisq27",
    "chatId": "cm7p6rik1001emqp0slgxgu1j",
    "sender": "user",
    "content": "What is predestination?",
    "timestamp": "2025-02-28T19:48:22.410Z"
   },
   {
    "id": "cm7p6rqc0001imqp0h9gywt2x",
    "chatId": "cm7p6rik1001emqp0slgxgu1j",
    "sender": "tool_summary",
    "toolName": "supplementalArticleSearch",
    "content": "Found 3 relevant theological articles on predestination from trusted sources.",
    "timestamp": "2025-02-28T19:48:30.401Z"
   },
   {
    "id": "cm7p6rqd0001jmqp0abc12345",
    "chatId": "cm7p6rik1001emqp0slgxgu1j",
    "sender": "gotQuestions",
    "content": "- [Providence and Predestination - Monergism](https://www.monergism.com/reformation-theology/blog/providence-and-predestination) _(Monergism)_\n- [What is predestination? - GotQuestions.org](https://www.gotquestions.org/predestination.html) _(GotQuestions)_\n- [What is Predestination? - Monergism](https://www.monergism.com/what-predestination) _(Monergism)_",
    "timestamp": "2025-02-28T19:48:32.401Z"
   },
   {
    "id": "cm7p6rxq0001kmqp0kdxt3qvt",
    "chatId": "cm7p6rik1001emqp0slgxgu1j",
    "sender": "CCEL",
    "content": "- [Calvin's Institutes, Book III, Chapter 21](https://ccel.org/ccel/calvin/institutes/institutes.v.xxii.html) - On Eternal Election",
    "timestamp": "2025-02-28T19:48:41.938Z"
   },
   {
    "id": "cm7p6rzqs001mmqp0jrawhfi1",
    "chatId": "cm7p6rik1001emqp0slgxgu1j",
    "sender": "parrot",
    "content": "Predestination is...",
    "timestamp": "2025-02-28T19:48:44.596Z"
   }
  ]
}

Note: The tool_summary messages include a toolName field that is parsed from the stored JSON content. This allows the frontend to display tool-specific UI components.

Implementation Guide

Front-end Integration Example

const handleStream = async (chatId: string, message: string) => {
  const response = await fetch('/api/parrot-chat', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({ chatId, message })
  });

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

  while (true) {
   const { value, done } = await reader.read();
   if (done) break;
   
   const lines = decoder.decode(value).split('\n');
   for (const line of lines) {
    if (!line.trim()) continue;
    
    const event = JSON.parse(line);
    switch (event.type) {
      case 'progress':
       updateProgress(event.title, event.content);
       break;
      case 'parrot':
       appendParrotMessage(event.content);
       break;
      case 'tool_progress':
       // Ephemeral - show but don't persist
       showToolProgress(event.toolName, event.message);
       break;
      case 'tool_summary':
       // Persistent - show and will be in chat history
       showToolSummary(event.toolName, event.content);
       break;
      case 'gotQuestions':
       showReferences(event.content);
       break;
      case 'CCEL':
       showCCELReferences(event.content);
       break;
      case 'conversationNameUpdated':
       // Update sidebar with new conversation name
       updateSidebarChatName(event.chatId, event.name);
       break;
      case 'done':
       finishStream();
       break;
    }
   }
  }
};

For complete implementation examples, see:

• Main Chat Page
• Chat Session Page

---

Denominations

The endpoint supports the following denomination:

1. Reformed Baptist (default)
2. Presbyterian
3. Wesleyan
4. Lutheran
5. Anglican
6. Pentecostal/Charismatic
7. Non-Denominational Evangelical

Each mode tailors its responses according to distinct theological perspectives on secondary issues while sharing a common foundation on core doctrines.

---

Calvinist Parrot Ministries

This work is part of the Calvinist Parrot Ministries, we exist to glorify God by creating and freely distributing AI tools that proclaim the Gospel, strengthen the Church, and equip believers across the globe.

Contact

For further questions or support, please reach out!

This is open source, so if you're interested in helping me development this, check out the GitHub repo.

Freely you have received; freely give.

• Matthew 10:8

Soli Deo Gloria

• Romans 11:36