Freshpaint Events API

openapi: 3.0.1
info:
  title: Freshpaint HTTP Events API
  description: The Freshpaint server-side HTTP API for sending events to Freshpaint from your backend. Events are sent as POST requests to the /track endpoint and are fanned out to your active destinations. The same endpoint is used to track custom events, identify users ($identify), and emit page and screen events. Authentication is performed with your environment token, supplied in the event payload as properties.token.
  termsOfService: https://www.freshpaint.io/legal/terms-of-service
  contact:
    name: Freshpaint Support
    url: https://documentation.freshpaint.io/reference/developer/http-api
  version: '1.0'
servers:
- url: https://api.perfalytics.com
  description: Freshpaint HTTP API ingestion host
security:
- EnvironmentToken: []
tags:
- name: Events
paths:
  /track:
    post:
      operationId: track
      tags:
      - Events
      summary: Send a server-side event to Freshpaint.
      description: Send a single server-side event to Freshpaint. The event is routed to all active destinations unless restricted via the $options property. Reserved event names ($identify, $page, $screen) drive identify, page, and screen behavior; any other value of `event` is treated as a custom tracked event. The environment token is supplied in properties.token.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
            examples:
              track:
                summary: Custom tracked event
                value:
                  event: Order Completed
                  properties:
                    distinct_id: user@example.com
                    token: YOUR_ENVIRONMENT_ID
                    time: 1719446400
                    revenue: 49.99
              identify:
                summary: Server-side identify
                value:
                  event: $identify
                  properties:
                    distinct_id: user@example.com
                    token: YOUR_ENVIRONMENT_ID
                    time: 1719446400
                    $user_props:
                      plan: pro
                      company: Acme
              page:
                summary: Page event
                value:
                  event: $page
                  properties:
                    distinct_id: user@example.com
                    token: YOUR_ENVIRONMENT_ID
                    time: 1719446400
                    name: Pricing
                    category: Marketing
                    url: https://www.example.com/pricing
      responses:
        '200':
          description: Event accepted for ingestion.
        '400':
          description: Malformed event payload or missing required properties.
        '429':
          description: Rate limited. The HTTP API enforces a 5000 request/second burst limit; throttle requests accordingly.
components:
  schemas:
    EventProperties:
      type: object
      required:
      - distinct_id
      - token
      - time
      properties:
        distinct_id:
          type: string
          description: Identifier that uniquely identifies the user that performed the event, usually an email address. Matches the identifier passed to freshpaint.identify().
          example: user@example.com
        token:
          type: string
          description: Your environment ID, available from the Server Side API section on the Sources page of the Freshpaint app.
          example: YOUR_ENVIRONMENT_ID
        time:
          type: integer
          format: int64
          description: Epoch time the event occurred, in seconds.
          example: 1719446400
        $device_id:
          type: string
          description: Optional device identifier used for stitching and deduplication.
        $insert_id:
          type: string
          description: Optional unique event identifier used for deduplication. When omitted, Freshpaint computes a value from time and $device_id.
        $ip:
          type: string
          description: Optional override of the captured IP address. By default the IP from which the event is sent is captured automatically.
        $user_props:
          type: object
          additionalProperties: true
          description: User properties to attach to the profile, primarily used with the $identify event.
        $options:
          type: object
          description: Optional destination routing controls. Pass a list of destinations the event should only go to, or a list of destinations the event should not go to.
          additionalProperties: true
      additionalProperties: true
      description: Event properties. In addition to the required distinct_id, token, and time, any custom properties may be included.
    Event:
      type: object
      required:
      - event
      - properties
      properties:
        event:
          type: string
          description: Name of the event. Use $identify for server-side identify, $page for a page event, $screen for a screen event, or any custom string for a tracked event.
          example: Order Completed
        properties:
          $ref: '#/components/schemas/EventProperties'
  securitySchemes:
    EnvironmentToken:
      type: apiKey
      in: query
      name: token
      description: Freshpaint authenticates server-side events with your environment ID (token). The token is supplied inside the event payload as properties.token rather than as a header or query string; this scheme documents the token-based, in-body authentication used by the HTTP API. Obtain the token from the Server Side API section of the Sources page in the Freshpaint app.