> ## 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.

# REST API

> 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.

## Authentication

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

```bash theme={null}
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:

```json theme={null}
{
  "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`

```bash theme={null}
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

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

### Response

```json theme={null}
{
  "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:

```bash theme={null}
# 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

```javascript theme={null}
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

```python theme={null}
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

| Status | Description                                                    |
| ------ | -------------------------------------------------------------- |
| 401    | Missing, invalid, or improperly formatted Authorization header |
| 404    | Agent not found                                                |
| 500    | Internal 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)