Send Events

Send events to Chippy Analytics to track user actions, app behavior, and custom metrics. Choose the endpoint that best fits your integration pattern.

POST /api/v1/events: Single Event

Send one event at a time. Best for real-time tracking where you want to fire an event immediately after a user action occurs.

Request Body

Field	Type	Required	Description
`app_id`	string	Yes	Your Chippy app identifier
`distinct_id`	string	Yes	A unique identifier for the user performing the action
`event_name`	string	Yes	Name of the event (e.g., `ticket_triaged`, `report_generated`)
`properties`	object	No	Arbitrary key-value pairs with additional event context
`timestamp`	string	No	ISO 8601 timestamp. Defaults to the current server time if omitted

Example 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": "ticket_triaged",
    "properties": {
      "urgency": "high",
      "team": "engineering"
    },
    "timestamp": "2026-02-09T12:00:00Z"
  }'

const response = await fetch("https://analytics.chippy.build/api/v1/events", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ak_live_xxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    app_id: "your-app-id",
    distinct_id: "user-123",
    event_name: "ticket_triaged",
    properties: {
      urgency: "high",
      team: "engineering",
    },
    timestamp: "2026-02-09T12:00:00Z",
  }),
});

import requests

response = requests.post(
    "https://analytics.chippy.build/api/v1/events",
    headers={
        "Authorization": "Bearer ak_live_xxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "app_id": "your-app-id",
        "distinct_id": "user-123",
        "event_name": "ticket_triaged",
        "properties": {
            "urgency": "high",
            "team": "engineering",
        },
        "timestamp": "2026-02-09T12:00:00Z",
    },
)

Response

202 Accepted

{
  "success": true,
  "message": "Event accepted"
}

Error Responses

400 Bad Request: missing required fields:

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

401 Unauthorized: invalid API key:

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

POST /api/v1/events/batch: Batch Events

Send up to 100 events in a single request. Best for high-volume ingestion where you buffer events and flush them periodically.

Request Body

Field	Type	Required	Description
`app_id`	string	Yes	Your Chippy app identifier (applied to all events in the batch)
`events`	array	Yes	Array of event objects (max 100)
`events[].distinct_id`	string	Yes	A unique identifier for the user
`events[].event_name`	string	Yes	Name of the event
`events[].properties`	object	No	Arbitrary key-value pairs with additional event context
`events[].timestamp`	string	No	ISO 8601 timestamp. Defaults to current server time

Example Request

curl -X POST https://analytics.chippy.build/api/v1/events/batch \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "your-app-id",
    "events": [
      {
        "distinct_id": "user-123",
        "event_name": "ticket_triaged",
        "properties": {
          "urgency": "high"
        }
      },
      {
        "distinct_id": "user-456",
        "event_name": "ticket_viewed",
        "properties": {
          "ticket_id": "T-1001"
        }
      }
    ]
  }'

const response = await fetch("https://analytics.chippy.build/api/v1/events/batch", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ak_live_xxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    app_id: "your-app-id",
    events: [
      {
        distinct_id: "user-123",
        event_name: "ticket_triaged",
        properties: { urgency: "high" },
      },
      {
        distinct_id: "user-456",
        event_name: "ticket_viewed",
        properties: { ticket_id: "T-1001" },
      },
    ],
  }),
});

import requests

response = requests.post(
    "https://analytics.chippy.build/api/v1/events/batch",
    headers={
        "Authorization": "Bearer ak_live_xxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "app_id": "your-app-id",
        "events": [
            {
                "distinct_id": "user-123",
                "event_name": "ticket_triaged",
                "properties": {"urgency": "high"},
            },
            {
                "distinct_id": "user-456",
                "event_name": "ticket_viewed",
                "properties": {"ticket_id": "T-1001"},
            },
        ],
    },
)

Response

202 Accepted

{
  "success": true,
  "message": "Batch accepted",
  "count": 2
}

The count field confirms how many events were accepted from the batch. If any individual event is malformed, the entire batch is rejected with a 400 error.

Error Responses

400 Bad Request: batch exceeds maximum size:

{
  "error": "Batch size exceeds maximum of 100 events"
}

POST /api/v1/events/track: SDK-Friendly Format

A flexible endpoint designed for SDK integrations. Accepts both camelCase and snake_case field names, and can receive a single event or an array of events.

Field Mapping

The track endpoint accepts alternate field names for convenience:

Accepted Field	Maps To
`event` or `event_name`	`event_name`
`distinctId` or `distinct_id`	`distinct_id`
`appId` or `app_id`	`app_id`

Example Request (Single Event)

curl -X POST https://analytics.chippy.build/api/v1/events/track \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "your-app-id",
    "distinctId": "user-123",
    "event": "ticket_triaged",
    "properties": {
      "urgency": "high",
      "team": "engineering"
    }
  }'

const response = await fetch("https://analytics.chippy.build/api/v1/events/track", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ak_live_xxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    appId: "your-app-id",
    distinctId: "user-123",
    event: "ticket_triaged",
    properties: {
      urgency: "high",
      team: "engineering",
    },
  }),
});

import requests

response = requests.post(
    "https://analytics.chippy.build/api/v1/events/track",
    headers={
        "Authorization": "Bearer ak_live_xxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "appId": "your-app-id",
        "distinctId": "user-123",
        "event": "ticket_triaged",
        "properties": {
            "urgency": "high",
            "team": "engineering",
        },
    },
)

Response

202 Accepted

{
  "success": true,
  "message": "Event accepted"
}

Choosing the Right Endpoint

Use Case	Endpoint	Why
Real-time user action tracking	`POST /api/v1/events`	Low latency, one event per request
High-volume ingestion or periodic flush	`POST /api/v1/events/batch`	Fewer HTTP requests, up to 100 events at once
SDK or client library integration	`POST /api/v1/events/track`	Flexible field names, accepts single or array payloads

For most server-side integrations, start with the single event endpoint. Switch to batch when you are sending more than a few events per second and want to reduce HTTP overhead.

​Send Events

​POST /api/v1/events: Single Event

​Request Body

​Example Request

​Response

​Error Responses

​POST /api/v1/events/batch: Batch Events

​Request Body

​Example Request

​Response

​Error Responses

​POST /api/v1/events/track: SDK-Friendly Format

​Field Mapping

​Example Request (Single Event)

​Response

​Choosing the Right Endpoint

Send Events

POST /api/v1/events: Single Event

Request Body

Example Request

Response

Error Responses

POST /api/v1/events/batch: Batch Events

Request Body

Example Request

Response

Error Responses

POST /api/v1/events/track: SDK-Friendly Format

Field Mapping

Example Request (Single Event)

Response

Choosing the Right Endpoint