Events

Note

This section requires authentication. Please refer to the Authentication section for more details.

Event Object

The event object is a representation of a user-generated action or interaction within the system. It captures actions such as button presses, image uploads, gestures, and any interaction that can be considered an "event" in the application.

Event Object Structure

Field	Type	Description
id	integer	Unique identifier for the event
name	string	The name of the event. Maximum 255 characters.
created_at	date	Timestamp when the event was first recorded in ISO8601 format
updated_at	date	Timestamp when the event was last updated in ISO8601 format
event_data	array	List of key-value metadata objects associated with the event
unique_users	integer	Number of unique users who triggered this event
occurrences	integer	Total number of times this event has occurred

Event Data Object Structure

Field	Type	Description
id	string	Unique identifier for the event data
key	string	Key name of the metadata
value	string	Value associated with the metadata key
created_at	date	Timestamp when the event data was created in ISO8601 format
updated_at	date	Timestamp when the event data was last updated in ISO8601 format
occurrences	integer	Number of times this specific metadata key-value pair has occurred

---

Create Event

This endpoint allows creating a new event associated with a Consumer. An event consists of a name and metadata in key-value format.

POST  /api/events

Headers

Header	Value
Authorization	Bearer {YOUR_AUTH_KEY}
Content-Type	application/json
Accept	application/json

Body Parameters

Required Parameters

Field	Type	Description	Example
name	string	Name of the event (max 255 characters)	App Opened
metadata	object	Object with metadata in "key": "value" format	{"device": "iPhone 12"}

Example Request

JSON

{
    "name": "2025-05-13T14:30:00Z",
    "metadata": {
        "device": "iPhone 12"
    }
}

Example Response

JSON

{
    "id": 166,
    "name": "App Opened new new",
    "created_at": "2025-05-29T14:13:10.000000Z",
    "updated_at": "2025-05-29T14:19:08.000000Z",
    "event_data": [
        {
            "id": "54a9d4ccb52a538ffebb3bb73c5f34fe",
            "key": "device",
            "value": "iPhone 12",
            "created_at": "2025-05-29T14:13:10.000000Z",
            "updated_at": "2025-05-29T14:19:08.000000Z",
            "occurrences": 5
        },
        {
            "id": "ce7676668bafb66c39cc88d6bc6b44fd",
            "key": "some",
            "value": "new",
            "created_at": "2025-05-29T14:13:10.000000Z",
            "updated_at": "2025-05-29T14:19:08.000000Z",
            "occurrences": 5
        }
    ],
    "unique_users": 3,
    "occurrences": 5
}

---

Batch Create Events

This endpoint allows creating multiple events in a single request. Each event must include a name and metadata.

POST  /api/events/batch

Headers

Header	Value
Authorization	Bearer {YOUR_AUTH_KEY}
Content-Type	multipart/form-data
Accept	application/json

Body Parameters

Required Parameters

Each item in the array must include:

Field	Type	Description	Example
name	string	Name of the event (max 255 characters)	App Opened
metadata	object	Object with metadata in "key": "value" format	{"device": "iPhone"}
session_id	integer	ID of the session associated with the event	101

Optional Parameters

Field	Type	Description	Example
created_at	string	ISO8601 formatted timestamp for the event	2025-05-13T14:30:00Z

Example Request

JSON

{
    "events": [
        {
            "name": "App Opened",
            "metadata": {
                "device": "iPhone 12"
            },
          "session_id": 101
        },
        {
            "name": "Button Clicked",
            "metadata": {
                "button_id": "submit"
            }
        },
        {
            "name": "Image Uploaded",
            "metadata": {
                "image_type": "profile_picture"
            },
            "created_at": "2025-05-13T14:30:00Z",
            "session_id": 102
        }
    ]
}

Example Response

JSON

{
    "message": "Events queued for processing."
}

---