Skip to main content

​
REST API

Use the REST API to integrate your agent into any application — mobile apps, backends, custom frontends, or third-party services.

​
Authentication

Create an Agent API Key for server-to-server access: 
curl -X POST https://api.thinnest.ai/agents/YOUR_AGENT_PUBLIC_ID/api-keys \
  -H "Authorization: Bearer $THINNESTAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Integration"
  }'
Response: 
{
  "id": 1,
  "name": "Backend Integration",
  "api_key": "agno_abc123xyz...",
  "key_preview": "agno_abc12..._xyz",
  "created_at": "2024-03-01T12:00:00Z"
}
[!WARNING] The api_key is only returned once upon creation. Store it securely.

​
Send a Message

​
POST /v1/agents/:agent_id/chat

curl -X POST https://api.thinnest.ai/v1/agents/YOUR_AGENT_PUBLIC_ID/chat \
  -H "Authorization: Bearer agno_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "session_id": "sess_789"
  }'

​
Request Parameters

FieldTypeRequiredDescription
messagestringYesThe user’s message
session_idstringNoSession ID for conversation continuity

​
Response

{
  "success": true,
  "response": "Our business hours are Monday to Friday, 9am to 5pm EST.",
  "session_id": "sess_789",
  "metadata": {
    "model": "gpt-4o",
    "latency_ms": 1450
  }
}

​
Session Management

Sessions maintain conversation context across messages. Pass the same session_id to continue a conversation: 
# First message
curl -X POST https://api.thinnest.ai/v1/agents/YOUR_AGENT_PUBLIC_ID/chat \
  -H "Authorization: Bearer agno_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{"message": "What is your return policy?", "session_id": "user_123_session"}'

# Follow-up (same session)
curl -X POST https://api.thinnest.ai/v1/agents/YOUR_AGENT_PUBLIC_ID/chat \
  -H "Authorization: Bearer agno_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{"message": "How long does it take?", "session_id": "user_123_session"}'
The agent remembers the full conversation within a session (based on the dashboard history retention).

​
Integration Examples

​
Node.js

const AGENT_ID = 'ag_pub_xyz789';
const API_KEY = 'agno_abc123xyz...';

const response = await fetch(`https://api.thinnest.ai/v1/agents/${AGENT_ID}/chat`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'Hello!',
    session_id: 'sess_001',
  }),
});

const data = await response.json();
console.log(data.response);

​
Python

import httpx

AGENT_ID = "ag_pub_xyz789"
API_KEY = "agno_abc123xyz..."

client = httpx.Client(
    base_url="https://api.thinnest.ai",
    headers={"Authorization": f"Bearer {API_KEY}"},
)

response = client.post(f"/v1/agents/{AGENT_ID}/chat", json={
    "message": "Hello!",
    "session_id": "sess_001",
})

print(response.json()["response"])

​
Error Handling

StatusDescription
401Missing, invalid, or improperly formatted Authorization header
404Agent not found
500Internal agent execution error

​
Best Practices

  • Reuse sessions for multi-turn conversations to preserve context
  • Store API keys securely — never expose them in client-side code (e.g. front-end React apps without a proxy)