Chat with Agent

Here’s the enhanced API Reference for “Chat with Agent”, including detailed behavior, cURL requests, and JavaScript (fetch) code examples.

---

💬 Chat with Agent (Natural Language to SQL)

These endpoints allow users to query their PostgreSQL database using text or voice. The API:

• Interprets natural language

• Generates SQL

• Executes queries on the provided database

• Returns results, refined answers, and even voice responses.

---

🔸 POST /chat – Query Database with Natural Language

Converts a plain-text prompt into SQL, executes it on the linked PostgreSQL database, and returns results.

---

📥 Request Body:

{
  "db_url": "postgresql://user:pass@host:5432/dbname",
  "prompt": "Show me the total revenue for Q1"
}

🔐 Auth Required: ✅ Yes (JWT required)

📤 Response:

{
  "used_tool": "RevenueSummaryTool",
  "sql_query": "SELECT SUM(amount) FROM sales WHERE ...",
  "result": [{ "sum": 102300 }],
  "refined_answer": "Total revenue for Q1 was $102,300",
  "token_usage": { "total_tokens": 342 },
  "params": { "quarter": "Q1" }
}

---

✅ Behavior:

• Detects database schema automatically

• Uses a reusable SQL “tool” if matched

• Fills placeholders (e.g., Q1, 2023, etc.)

• Executes query

• Returns refined natural-language response

---

✅ cURL Example

curl -X POST https://api.yourdomain.com/chat \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "db_url": "postgresql://user:pass@host:5432/sales_db",
    "prompt": "Show me the total revenue for Q1"
  }'

---

✅ JS (fetch) Example

await fetch("https://api.yourdomain.com/chat", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + token,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    db_url: "postgresql://user:pass@host:5432/sales_db",
    prompt: "Show me the total revenue for Q1"
  })
});

---

🔸 POST /audio-chat – Voice-to-SQL Agent

Accepts audio input (or text) and returns both:

• Text result

• Base64-encoded audio response

---

📥 Form-Data Fields:

Field	Type	Required	Description
audio	file	optional	WAV/MP3 file of your voice
text	string	optional	Text fallback if no audio

🔐 Auth Required: ✅ Yes

---

📤 Response:

{
  "transcription": "Show me orders over $500",
  "audio_content": "<base64_audio>",
}

---

✅ Voice Flow:

1. Audio is transcribed via ElevenLabs STT

2. Prompt is run through the /chat engine

3. Final response is converted back to voice (TTS)

4. Both text + base64 voice are returned

---

✅ cURL Example (with text only)

curl -X POST https://api.yourdomain.com/audio-chat \
  -H "Authorization: Bearer <your_token>" \
  -F "text=Show me orders over $500"

✅ JS Example (text-only query)

const form = new FormData();
form.append("text", "Show me orders over $500");

await fetch("https://api.yourdomain.com/audio-chat", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + token
  },
  body: form
});

---

✅ JS Example (with audio file)

const form = new FormData();
form.append("audio", audioBlob, "query.mp3");

await fetch("https://api.yourdomain.com/audio-chat", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + token
  },
  body: form
});

---

🔄 Ideal Use Cases:

• Integrate into business dashboards

• Enable “Ask your data” voice/chat in SaaS apps

• Embed SQL reasoning in analytics tools

---

Let me know when you're ready to move on to: 🎙 Voice Services (STT & TTS) APIs.