Skip to main content

​
Endpoint

POST /api/track-download-supabase Tracks component downloads for analytics. This endpoint is called automatically by the CLI whenever a user installs a component.

​
Request

​
Headers

​
Content-Type
string
required
Must be application/json
​
User-Agent
string
Client user agent string (automatically captured)

​
Body Parameters

​
type
string
required
Component type. Must be one of:
  • agent
  • command
  • setting
  • hook
  • mcp
  • skill
  • template
​
name
string
required
Component name. Maximum 255 characters.
​
path
string
Component path in the repository
​
category
string
Component category (e.g., “development-team”, “automation”)
​
cliVersion
string
Version of the CLI tool used for installation

​
Example Request

curl -X POST https://www.aitmpl.com/api/track-download-supabase \
  -H "Content-Type: application/json" \
  -H "User-Agent: claude-code-templates/1.0.0" \
  -d '{
    "type": "agent",
    "name": "frontend-developer",
    "path": "cli-tool/components/agents/development-team/frontend-developer.md",
    "category": "development-team",
    "cliVersion": "1.0.0"
  }'

​
Response

​
Success Response (200 OK)

​
success
boolean
Always true on success
​
message
string
Confirmation message
​
data
object
Download information
​
data.type
string
Component type
​
data.name
string
Component name
​
data.timestamp
string
ISO 8601 timestamp of the download

​
Example Success Response

{
  "success": true,
  "message": "Download tracked successfully",
  "data": {
    "type": "agent",
    "name": "frontend-developer",
    "timestamp": "2026-02-28T12:34:56.789Z"
  }
}

​
Error Responses

​
400 Bad Request - Invalid Component Type

{
  "error": "Invalid component type"
}

​
400 Bad Request - Missing Required Fields

{
  "error": "Component type and name are required"
}

​
400 Bad Request - Name Too Long

{
  "error": "Component name too long"
}

​
405 Method Not Allowed

{
  "error": "Method not allowed",
  "allowed": ["POST"]
}

​
500 Internal Server Error

{
  "error": "Internal server error",
  "message": "Failed to track download",
  "details": "Database insert failed: connection timeout"
}
Note: The details field is only included in development mode.

​
Data Storage

Download events are stored in two Supabase tables:

​
component_downloads

Stores individual download records with:
  • Component metadata (type, name, path, category)
  • User information (IP address, country, user agent)
  • CLI version
  • Timestamp

​
download_stats

Aggregated statistics using upsert:
  • Total downloads per component
  • Last download timestamp
  • Automatically updated via onConflict on (component_type, component_name)

​
Metadata Captured

The endpoint automatically captures:
​
IP Address
string
Extracted from headers in order:
  1. x-forwarded-for (first IP)
  2. x-real-ip
  3. Connection remote address
  4. Fallback: 127.0.0.1
​
Country
string
Extracted from Vercel geo header x-vercel-ip-country
​
User Agent
string
From user-agent request header

​
Rate Limiting

No explicit rate limits are enforced, but requests are subject to:
  • Vercel serverless function execution limits (10s timeout)
  • Supabase connection pool limits

​
CORS Support

The endpoint supports CORS with: 
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, User-Agent
Preflight OPTIONS requests return 200 OK.

​
Notes

  • The endpoint never fails the user’s installation if tracking fails
  • Stats update errors are logged but don’t return 500 responses
  • All timestamps are stored in ISO 8601 format
  • The endpoint is idempotent (duplicate downloads are recorded separately)

Build docs developers (and LLMs) love

Get started for freeTalk to us