Chat with Agent
Send a message to an agent using API key authentication.
For external integrations, use the V1 agent chat endpoint with an Agent API Key. Create API keys from the dashboard or via the API Keys endpoint.
POST
/v1/agents/{agent_id}/chatChat with an agent using API key authentication.
Path Parameters
Target agent ID (format: ag_*)
Authentication
This endpoint uses Agent API Keys (not Auth0 JWT). Pass the key in the Authorization header:
curl -X POST https://api.thinnest.ai/v1/agents/ag_c47e7c97_b2f2/chat \
-H "Authorization: Bearer ak_your_agent_api_key" \
-H "Content-Type: application/json" \
-d '{"message": "Hello"}'Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | Target agent's public ID (ag_*) |
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
message | string | Yes | — | User message text |
session_id | string | No | Auto-generated | Session ID for conversation memory. Reuse the same ID to continue a conversation |
Session Behavior
- With
session_id: The agent remembers previous messages in this session. Use for multi-turn conversations. - Without
session_id: A new session is created automatically. Each request is treated as independent.
Response 200
{
"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_jane_001",
"usage": {
"input_tokens": 45,
"output_tokens": 32,
"total_tokens": 77
}
}Response Fields
| Field | Type | Description |
|---|---|---|
response | string | Agent's text response |
session_id | string | Session ID (reuse for follow-up messages) |
usage.input_tokens | integer | Tokens in the prompt |
usage.output_tokens | integer | Tokens in the response |
usage.total_tokens | integer | Total tokens consumed |
Example — Multi-Turn Conversation
Turn 1:
// Request
{ "message": "What products do you sell?", "session_id": "sess_001" }
// Response
{ "response": "We sell three main product lines: ...", "session_id": "sess_001" }Turn 2:
// Request (same session_id continues the conversation)
{ "message": "How much does the premium plan cost?", "session_id": "sess_001" }
// Response (agent remembers context from Turn 1)
{ "response": "The premium plan for our Enterprise product is $99/month...", "session_id": "sess_001" }Errors
| Code | Description |
|---|---|
401 | Missing or invalid API key |
402 | Insufficient balance |
404 | Agent not found |
429 | Rate limit exceeded |