Create an event

Track timestamped events representing user or organization actions. Events are used to track important business outcomes (signups, conversions, upgrades, cancellations, etc.) and integrate them into Greenflash’s quality metrics. Each event can be optionally linked to a conversation, user, and organization.

POST /events

cURL

cURL

curl --request POST \
  --url https://www.greenflash.ai/api/v1/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventType": "<string>",
  "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "value": "<string>",
  "externalUserId": "<string>",
  "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "externalOrganizationId": "<string>",
  "organizationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "externalConversationId": "<string>",
  "conversationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "influence": "neutral",
  "qualityImpactScore": 0,
  "valueType": "text",
  "eventAt": "2023-11-07T05:31:56Z",
  "properties": {},
  "insertId": "<string>",
  "sampleRate": 0.5,
  "forceSample": true
}
'

200

{
  "success": true,
  "eventId": "123e4567-e89b-12d3-a456-426614174000"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request payload for creating events.

eventType · string · required

The specific name or category of the event being tracked (e.g., "trial_started", "signup", "feature_usage"). This helps categorize events for analysis and often pairs with "value" to define the outcome.

Minimum string length: 1

productId · string<uuid> · required

The unique identifier of the Greenflash product associated with this event. This links the event to a specific product context.

value · string · required

The specific value associated with the event (e.g., "99.00", "5", "premium_plan"). This pairs with "valueType" and "eventType" to define the magnitude or content of the event.

externalUserId · string

Your system's unique identifier for the user associated with this event. Used to map Greenflash events back to your user records.

userId · string<uuid>

The unique Greenflash identifier for the user. Provide this if you already have the Greenflash User ID; otherwise, use "externalUserId".

externalOrganizationId · string

Your system's unique identifier for the organization associated with this event. Used to map events to your customer accounts.

organizationId · string<uuid>

The unique Greenflash identifier for the organization. Provide this if you have the Greenflash Organization ID.

externalConversationId · string

Your system's unique identifier for the conversation or thread where this event occurred.

conversationId · string<uuid>

The unique Greenflash identifier for the conversation. Links the event to a specific chat session in Greenflash.

influence · enum<string> · default: neutral

A high-level categorization of how this event generally "changed things" or influenced quality (positive, negative, or neutral). Use this for broad classification of outcomes.

Available options: positive, negative, neutral

qualityImpactScore · number · default: 0

A precise numeric score between -1.0 and 1.0 for direct control over the quality impact. If omitted, it is automatically derived from the "influence" field.

Required range: -1 <= x <= 1

valueType · enum<string> · default: text

Defines the format of the "value" field (currency, numeric, or text). This ensures the value is interpreted and processed correctly.

Available options: currency, numeric, text, boolean

eventAt · string<date-time>

The ISO 8601 timestamp of when the event actually occurred. Defaults to the current time if not provided. Useful for backdating historical events.

properties · object

A key-value object for storing additional, unstructured context about the event (e.g., { source: "web_app", campaign_id: "123" }). Useful for custom filtering.

Show child attributes

insertId · string

A unique key for idempotency. If you retry a request with the same insertId, it prevents creating a duplicate event record.

sampleRate · number

Controls the percentage of requests that are ingested (0.0 to 1.0). For example, 0.1 means 10% of events will be stored. Defaults to 1.0 (all events ingested). Sampling is deterministic based on event type and organization.

Required range: 0 <= x <= 1

forceSample · boolean

When true, bypasses sampling and ensures this event is always ingested regardless of sampleRate. Use for critical events that must be captured.

Response

200

application/json

Event created successfully or existing event returned (idempotent)

Success response for event creation.

success · boolean · required

Whether the API call was successful.

eventId · string · required

The unique Greenflash ID of the event record that was created.