Analytics API Overview

The Chippy Analytics API lets you collect events, identify users, and monitor app usage programmatically. Use it to send custom events from your backend, associate user traits for segmentation, and verify service health.

Base URL

All API requests are made to:

https://analytics.chippy.build

Authentication

Authenticate every request with a Bearer token in the Authorization header. API keys are managed in the Chippy dashboard under your organization settings.

Authorization: Bearer ak_live_xxxxxxxxxxxxxxxx

API keys beginning with ak_live_ are production keys. Keep them secret and never expose them in client-side code.

Example authenticated request

curl -X POST https://analytics.chippy.build/api/v1/events \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"app_id": "your-app-id", "distinct_id": "user-123", "event_name": "page_viewed"}'

Rate Limits

Each endpoint enforces its own rate limit per API key.

Endpoint	Limit	Window
POST /api/v1/events	1,000 requests	per minute, per API key
POST /api/v1/events/batch	100 requests	per minute, per API key
POST /api/v1/events/track	100 requests	per minute, per API key
POST /api/v1/identify	500 requests	per minute, per API key

Every response includes rate limit headers so you can track your usage:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

If you hit a rate limit, back off and retry after the X-RateLimit-Reset timestamp. Batch endpoints are the most efficient way to send high volumes of events.

HTTP Status Codes

Status	Meaning
`202 Accepted`	The request was accepted and will be processed asynchronously
`400 Bad Request`	The request body is malformed or missing required fields
`401 Unauthorized`	The API key is missing, invalid, or revoked
`429 Too Many Requests`	You have exceeded the rate limit for this endpoint

Error Response Format

All errors return a JSON object with an error field describing what went wrong.

{
  "error": "Error message description"
}

Example error responses

400 Bad Request: missing a required field:

{
  "error": "Missing required field: event_name"
}

401 Unauthorized: invalid API key:

{
  "error": "Invalid or expired API key"
}

429 Too Many Requests: rate limit exceeded:

{
  "error": "Rate limit exceeded. Retry after 1707480120"
}

API Endpoints

Send Events

Track user actions and app behavior with single, batch, or SDK-friendly event endpoints.

Identify Users

Associate traits and properties with users for segmentation and analysis.

Health Check

Monitor analytics service status and component health.

​Analytics API Overview

​Base URL

​Authentication

​Example authenticated request

​Rate Limits

​HTTP Status Codes

​Error Response Format

​Example error responses

​API Endpoints

Send Events

Identify Users

Health Check

Analytics API Overview

Base URL

Authentication

Example authenticated request

Rate Limits

HTTP Status Codes

Error Response Format

Example error responses

API Endpoints