> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useturret.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Simple, powerful API for tracking user events and gaining insights

## Welcome to the Turret API

Turret is a product analytics API designed for AI/LLM applications. It provides:

* **Semantic Topic Clustering**: Automatically groups similar user messages/prompts by meaning using embeddings
* **User Journey Tracking**: Tracks how users flow through different topics within conversations

<Card title="Single Endpoint Design" icon="zap" href="/api-reference/endpoint/track">
  One endpoint to track all your events - simple and powerful
</Card>

## Authentication

All API requests must include your project API key in the `X-API-Key` header:

```bash theme={null}
curl -X POST https://api.useturret.com/track \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json"
```

<Warning>
  Never expose your API key in client-side code. Always make API calls from your backend services.
</Warning>

## Base URL

All API requests should be made to:

```
https://api.useturret.com
```

## Request Format

All requests must:

* Use HTTPS
* Include `Content-Type: application/json` header
* Include `X-API-Key` header with your project API key
* Send data as JSON in the request body

## Basic Request Example

```json theme={null}
{
  "name": "user_prompt",
  "session_id": "conv_abc123",
  "user_id": "user_456",
  "metadata": {
    "prompt": "How do I reset my password?"
  }
}
```

## Field Reference

| Field        | Required    | Description                                                                                                                  |
| ------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `name`       | Yes         | Event name (e.g., "user\_prompt", "search\_query"). Used to categorize events.                                               |
| `session_id` | Recommended | Your conversation/thread ID. Critical for journey tracking. Events with the same session\_id are connected into a user flow. |
| `user_id`    | Optional    | Your user's ID. Enables cross-session analysis.                                                                              |
| `metadata`   | Yes         | Object containing the data to cluster. The key (e.g., "prompt") becomes the clustering dimension.                            |

## Response Format

All responses are returned as JSON with the following structure:

### Success Response

```json theme={null}
{
  "success": true,
  "message": "Event tracked successfully",
  "event_id": "evt_1234567890"
}
```

### Error Response

```json theme={null}
{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

## Rate Limits

Turret implements rate limiting to ensure service quality:

* **Free trial**: 250k total events (within 14 days)
* **Pro plan**: 1,000,000 events per month
* **Business plan**: 10,000,000 events per month
* **Enterprise**: Custom limits

When you exceed your rate limit, you'll receive a `429 Too Many Requests` response with details about when you can retry.

## Error Codes

Common error codes you might encounter:

| Code                     | Description                                  |
| ------------------------ | -------------------------------------------- |
| `INVALID_API_KEY`        | The provided API key is invalid or missing   |
| `RATE_LIMIT_EXCEEDED`    | You have exceeded your event limit           |
| `INVALID_REQUEST`        | The request format is incorrect              |
| `MISSING_REQUIRED_FIELD` | Required fields are missing from the request |
| `TEXT_TOO_LONG`          | Metadata text exceeds maximum length         |

## Metadata Field Types

Turret automatically detects and classifies your metadata fields:

| Type       | Description            | Dashboard Feature               |
| ---------- | ---------------------- | ------------------------------- |
| **text**   | Free-form text content | Semantic clustering into topics |
| **enum**   | Categorical values     | Segmentation and filtering      |
| **number** | Numeric values         | Aggregation                     |

Field types are detected on first event and re-validated as more data arrives. You can override detected types in the dashboard Settings → Metadata tab.

## Getting Started

1. **Get your API key** from the [Turret Dashboard](https://dashboard.useturret.com)
2. **Make your first request** to `/track` with event data
3. **View your results** in the dashboard to see automatic clustering and journeys

<Card title="Track Your First Event" icon="rocket" href="/api-reference/endpoint/track">
  Learn how to send events to Turret
</Card>