openapi: 3.0.1
info:
  title: Freshpaint HTTP 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
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:
  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.
  schemas:
    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'
    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.
security:
  - EnvironmentToken: []