> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Send Message
> Send a message to an agent and receive a response.
```bash cURL theme={null}
curl -X POST https://api.thinnest.ai/chat \
-H "Authorization: Bearer $THINNESTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "ag_c47e7c97_b2f2",
"message": "What are your business hours?",
"session_id": "sess_customer_001"
}'
```
```python Python theme={null}
import requests
url = "https://api.thinnest.ai/chat"
headers = {
"Authorization": "Bearer " + "YOUR_THINNESTAI_API_KEY",
"Content-Type": "application/json",
}
payload = {
"agent_id": "ag_c47e7c97_b2f2",
"message": "What are your business hours?",
"session_id": "sess_customer_001"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.thinnest.ai/chat", {
method: "POST",
headers: {
"Authorization": "Bearer " + "YOUR_THINNESTAI_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
"agent_id": "ag_c47e7c97_b2f2",
"message": "What are your business hours?",
"session_id": "sess_customer_001"
}),
});
const data = await response.json();
console.log(data);
```
```go Go theme={null}
package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
payload := []byte(`{
"agent_id": "ag_c47e7c97_b2f2",
"message": "What are your business hours?",
"session_id": "sess_customer_001"
}`)
req, _ := http.NewRequest("POST", "https://api.thinnest.ai/chat", bytes.NewBuffer(payload))
req.Header.Set("Authorization", "Bearer YOUR_THINNESTAI_API_KEY")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
```
***
## Request Body
Target agent ID (ag\_\*)
User message text
Session ID for conversation memory. Reuse to continue a conversation
Enable streaming response (use [Stream endpoint](/api-reference/chat/stream) instead)
Additional context passed to the agent (e.g., user info, page URL)
***
## Response `200`
```json 200 theme={null}
{
"response": "Our business hours are Monday through Friday, 9 AM to 6 PM EST. We're also available on Saturdays from 10 AM to 2 PM.",
"session_id": "sess_customer_001",
"usage": {
"input_tokens": 45,
"output_tokens": 32,
"total_tokens": 77
},
"tool_calls": []
}
```
### Response Fields
Agent's text response
Session ID — reuse for follow-up messages
Tokens consumed by the prompt
Tokens in the agent's response
Total tokens consumed (billed)
Tools the agent invoked during this response
***
## Example with Metadata
```json theme={null}
{
"agent_id": "ag_c47e7c97_b2f2",
"message": "I need help with my order",
"session_id": "sess_customer_001",
"metadata": {
"user_name": "Jane Doe",
"user_email": "jane@example.com",
"page_url": "https://store.example.com/orders/12345"
}
}
```
***
## Errors
| Code | Description |
| ----- | --------------------------------- |
| `401` | Missing or invalid authentication |
| `402` | Insufficient balance |
| `404` | Agent not found |
| `429` | Rate limit exceeded |
## OpenAPI
````yaml POST /chat
openapi: 3.1.0
info:
title: ThinnestAI API
description: REST API for ThinnestAI — build, deploy, and manage AI agents.
version: 1.0.0
servers: []
security: []
tags:
- name: Agents
description: Create, configure, and manage AI agents
- name: Chat
description: Send messages and get AI responses from agents
- name: Knowledge
description: Upload files, URLs, and text to agent knowledge bases
- name: Sessions
description: View and manage chat sessions and message history
- name: Voice
description: Start and manage voice call sessions
- name: Recordings
description: Manage voice call recordings
- name: Campaigns
description: Create and run automated outreach campaigns
- name: Webhooks
description: Register webhook endpoints for real-time event notifications
- name: Evaluations
description: Run and track agent evaluation benchmarks
- name: Analytics
description: Query agent performance metrics and usage data
- name: Agent Tools
description: View and manage tools attached to agents
- name: BYOK
description: >-
Bring Your Own Key — manage credentials for LLM/STT/TTS providers,
telephony BYOK (Vobiz/Twilio/Plivo/Exotel/Telnyx), and tool-specific BYOK
(Razorpay UPI Payment, Surepass Aadhaar eKYC)
paths:
/chat:
post:
summary: Embed Chat
description: |-
Handle chat messages from embedded widget.
Features:
- Origin validation against allowed domains
- Rate limiting (20 RPM default, aligned with OpenAI free tier)
- Flow-based agent support (GraphExecutor)
- Simple agent support (Agno Agent with knowledge)
- Session persistence
- Billing to agent owner
operationId: embed_chat_chat_post
parameters:
- name: origin
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Origin
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmbedChatRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
EmbedChatRequest:
properties:
publish_id:
type: string
title: Publish Id
message:
type: string
title: Message
session_id:
anyOf:
- type: string
- type: 'null'
title: Session Id
type: object
required:
- publish_id
- message
title: EmbedChatRequest
description: Request schema for embed chat messages.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
````