Integrate your thinnestAI agent into any application using the REST API for server-to-server communication.

REST API

Use the REST API to integrate your agent into any application — mobile apps, backends, custom frontends, or third-party services. The API supports streaming responses, session management, and full conversation control.

Authentication

Create an Agent API Key for server-to-server access:

curl -X POST https://api.thinnest.ai/agents/AGENT_ID/api-keys \
  -H "Authorization: Bearer $THINNESTAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Integration"
  }'

Response:

{
  "id": 1,
  "key": "ak_abc123xyz",
  "agent_id": "agent_abc123",
  "name": "Backend Integration"
}

Send a Message

POST `/v1/agents/:agent_id/chat`

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

Request Parameters

Field	Type	Required	Description
`message`	string	Yes	The user's message
`session_id`	string	No	Session ID for conversation continuity

Response (Non-Streaming)

{
  "response": "Our business hours are Monday to Friday, 9am to 5pm EST.",
  "session_id": "sess_789",
  "tokens_used": 145
}

Response (Streaming)

When streaming is enabled, the response is a Server-Sent Events (SSE) stream:

data: {"type": "content", "content": "Our business"}
data: {"type": "content", "content": " hours are Monday"}
data: {"type": "content", "content": " to Friday, 9am to 5pm EST."}
data: {"type": "done", "session_id": "sess_789", "tokens_used": 145}

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/AGENT_ID/chat \
  -H "Authorization: Bearer ak_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{"message": "What is your return policy?", "session_id": "sess_001"}'

# Follow-up (same session)
curl -X POST https://api.thinnest.ai/v1/agents/AGENT_ID/chat \
  -H "Authorization: Bearer ak_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{"message": "How long does it take?", "session_id": "sess_001"}'

The agent remembers the full conversation within a session.

Integration Examples

Python

import httpx

AGENT_ID = "agent_abc123"
API_KEY = "ak_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"])

Node.js

const AGENT_ID = 'agent_abc123';
const API_KEY = 'ak_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);

Streaming (Node.js)

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: 'Tell me about your products',
  }),
});

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

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value, { stream: true });
  const lines = chunk.split('\n').filter(l => l.startsWith('data: '));

  for (const line of lines) {
    const event = JSON.parse(line.slice(6));
    if (event.type === 'content') {
      process.stdout.write(event.content);
    }
  }
}

Rate Limits

Tier	Requests/min	Requests/day
Free	20	1,000
Pro	60	10,000
Enterprise	Custom	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1709830800

Error Handling

Status	Code	Description
400	`invalid_request`	Missing or invalid parameters
401	`unauthorized`	Invalid or missing API key
404	`agent_not_found`	Agent ID not found
429	`rate_limited`	Too many requests
500	`internal_error`	Server error

Best Practices

Reuse sessions for multi-turn conversations to preserve context
Use streaming for responsive user experiences
Handle rate limits with exponential backoff
Store API keys securely — never expose them in client-side code

REST API

On this page