Skip to main content

​
Welcome to the Turret API

Turret provides a simple HTTP API for tracking user events with free-form text metadata. Our API analyzes this metadata to automatically detect patterns and group similar events.

Single Endpoint Design

One endpoint to track all your events - simple and powerful

​
Authentication

All API requests must include your project API key in the X-Api-Key header: 
curl -X POST https://api.useturret.com/track \
  -H "X-Api-Key: your_project_api_key" \
  -H "Content-Type: application/json"
Never expose your API key in client-side code. Always make API calls from your backend services.

​
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

​
Response Format

All responses are returned as JSON with the following structure:

​
Success Response

{
  "success": true,
  "message": "Event tracked successfully",
  "event_id": "evt_1234567890"
}

​
Error Response

{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}

​
Rate Limits

Turret implements rate limiting to ensure service quality:
  • Free tier: 10,000 events per month
  • Pro tier: 100,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:
CodeDescription
INVALID_API_KEYThe provided API key is invalid or missing
RATE_LIMIT_EXCEEDEDYou have exceeded your monthly event limit
INVALID_REQUESTThe request format is incorrect
MISSING_REQUIRED_FIELDRequired fields are missing from the request
TEXT_TOO_LONGMetadata text exceeds maximum length

​
Getting Started

  1. Get your API key from the Turret Dashboard
  2. Make your first request to /track with event data
  3. View your results in the dashboard to see automatic clustering

Track Your First Event

Learn how to send events to Turret