> ## Documentation Index > Fetch the complete documentation index at: https://docs.greenflash.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml https://www.greenflash.ai/api/openapi post /events openapi: 3.1.0 info: title: Greenflash API Reference version: 1.0.0 description: >- Greenflash endpoints for capturing interactions, managing prompts, and identifying users. servers: - url: https://www.greenflash.ai/api/v1 description: Greenflash API v1 security: [] tags: - name: Interactions description: Capture interactions between users and AI - name: Business Events description: Capture business events - name: Analytics description: Understand chat and agentic interactions analyses - name: Inbox description: Review flagged conversations - name: Segments description: Manage user segments - name: Prompts description: Manage prompts - name: Chat description: Stream chat and agentic conversations - name: Models description: Manage AI models - name: Products description: Manage products - name: Users description: Manage users - name: Organizations description: Manage organizations paths: /events: post: tags: - Business Events summary: Create an event description: >- 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. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateEventRequest' responses: '200': description: Event created successfully or existing event returned (idempotent) content: application/json: schema: $ref: '#/components/schemas/CreateEventResponse' example: success: true eventId: 123e4567-e89b-12d3-a456-426614174000 '400': description: Invalid request - validation error content: application/json: schema: type: object properties: success: type: boolean description: Whether the API call was successful (false for errors). error: type: string description: Error message describing what went wrong. description: Error response for event creation operations. example: success: false error: 'Validation error: productId is required' '401': description: Unauthorized - invalid or missing API key content: application/json: schema: type: object properties: success: type: boolean description: Whether the API call was successful (false for errors). error: type: string description: Error message describing what went wrong. description: Error response for event creation operations. example: success: false error: Unauthorized '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean description: Whether the API call was successful (false for errors). error: type: string description: Error message describing what went wrong. description: Error response for event creation operations. example: success: false error: Internal server error security: - bearerAuth: [] x-codeSamples: - lang: JavaScript source: |- import Greenflash from 'greenflash'; const client = new Greenflash({ apiKey: process.env['GREENFLASH_API_KEY'], // This is the default and can be omitted }); const createEventResponse = await client.events.create({ eventType: 'x', productId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', value: 'value', }); console.log(createEventResponse.eventId); - lang: Python source: |- import os from greenflash import Greenflash client = Greenflash( api_key=os.environ.get("GREENFLASH_API_KEY"), # This is the default and can be omitted ) create_event_response = client.events.create( event_type="x", product_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", value="value", ) print(create_event_response.event_id) components: schemas: CreateEventRequest: type: object properties: eventType: type: string minLength: 1 description: >- 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. productId: type: string format: uuid description: >- The unique identifier of the Greenflash product associated with this event. This links the event to a specific product context. externalUserId: type: string description: >- Your system's unique identifier for the user associated with this event. Used to map Greenflash events back to your user records. userId: type: string format: uuid description: >- The unique Greenflash identifier for the user. Provide this if you already have the Greenflash User ID; otherwise, use "externalUserId". externalOrganizationId: type: string description: >- Your system's unique identifier for the organization associated with this event. Used to map events to your customer accounts. organizationId: type: string format: uuid description: >- The unique Greenflash identifier for the organization. Provide this if you have the Greenflash Organization ID. externalConversationId: type: string description: >- Your system's unique identifier for the conversation or thread where this event occurred. conversationId: type: string format: uuid description: >- The unique Greenflash identifier for the conversation. Links the event to a specific chat session in Greenflash. influence: type: string enum: - positive - negative - neutral default: neutral description: >- 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. qualityImpactScore: type: number minimum: -1 maximum: 1 default: 0 description: >- 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. value: type: string description: >- 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. valueType: type: string enum: - currency - numeric - text - boolean default: text description: >- Defines the format of the "value" field (currency, numeric, or text). This ensures the value is interpreted and processed correctly. eventAt: type: string format: date-time description: >- The ISO 8601 timestamp of when the event actually occurred. Defaults to the current time if not provided. Useful for backdating historical events. properties: type: object additionalProperties: {} description: >- A key-value object for storing additional, unstructured context about the event (e.g., { source: "web_app", campaign_id: "123" }). Useful for custom filtering. insertId: type: string description: >- A unique key for idempotency. If you retry a request with the same insertId, it prevents creating a duplicate event record. sampleRate: type: number minimum: 0 maximum: 1 description: >- 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. forceSample: type: boolean description: >- When true, bypasses sampling and ensures this event is always ingested regardless of sampleRate. Use for critical events that must be captured. required: - eventType - productId - value description: Request payload for creating events. CreateEventResponse: type: object properties: success: type: boolean description: Whether the API call was successful. eventId: type: string description: The unique Greenflash ID of the event record that was created. required: - success - eventId description: Success response for event creation. securitySchemes: bearerAuth: type: http scheme: bearer ````