Statsig Events API

openapi: 3.1.0
info:
  title: Statsig Client SDK Audit Logs Events API
  description: The Statsig Client SDK API provides endpoints that power Statsig's client-side SDKs for JavaScript, React, React Native, iOS, Android, Unity, and other platforms. Client SDKs use Client-SDK Keys that are safe to embed in mobile apps and front-end web applications. They access the initialize endpoint to retrieve all evaluated gates, configs, and experiments for a given user, and the log_event endpoint for sending analytics events. The SDKs handle local evaluation, caching, and automatic error handling for performant client-side feature flagging.
  version: 1.0.0
  contact:
    name: Statsig Support
    url: https://statsig.com/support
  termsOfService: https://statsig.com/terms
servers:
- url: https://api.statsig.com/v1
  description: Statsig API Server
security:
- clientSdkKey: []
tags:
- name: Events
  description: Endpoints for logging custom events and exposure data from client-side applications.
paths:
  /log_event:
    post:
      operationId: logClientEvent
      summary: Log client events
      description: Logs one or more events from the client SDK to Statsig for analytics and experiment analysis. Events include exposure events automatically generated by the SDK and custom events logged by the application. The STATSIG-CLIENT-TIME header is required for timestamp normalization.
      tags:
      - Events
      parameters:
      - name: STATSIG-CLIENT-TIME
        in: header
        required: true
        schema:
          type: integer
          format: int64
        description: Client-side timestamp in milliseconds since epoch, used to normalize event timestamps and account for clock skew.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - events
              properties:
                events:
                  type: array
                  items:
                    $ref: '#/components/schemas/StatsigEvent'
                  description: An array of events to log.
                statsigMetadata:
                  type: object
                  description: SDK metadata including SDK type, version, and session info.
      responses:
        '202':
          description: Events accepted for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the events were successfully accepted.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Error message describing the authentication failure.
  schemas:
    StatsigUser:
      type: object
      description: The user object representing the end user. A userID is required for consistent evaluation results across requests.
      properties:
        userID:
          type: string
          description: A unique identifier for the user.
        email:
          type: string
          format: email
          description: The email address of the user.
        ip:
          type: string
          description: The IP address of the user.
        userAgent:
          type: string
          description: The user agent string.
        country:
          type: string
          description: The two-letter country code.
        locale:
          type: string
          description: The locale identifier.
        appVersion:
          type: string
          description: The application version.
        custom:
          type: object
          additionalProperties: true
          description: Custom properties for targeting rules.
        privateAttributes:
          type: object
          additionalProperties: true
          description: Private attributes used for evaluation but not logged.
        customIDs:
          type: object
          additionalProperties:
            type: string
          description: Custom identifier mappings.
    StatsigEvent:
      type: object
      description: An event object for logging custom or exposure events.
      required:
      - user
      - eventName
      - time
      properties:
        user:
          $ref: '#/components/schemas/StatsigUser'
        eventName:
          type: string
          description: The name of the event.
        time:
          type: integer
          format: int64
          description: Timestamp in milliseconds since epoch.
        value:
          oneOf:
          - type: string
          - type: number
          description: An optional value associated with the event.
        metadata:
          type: object
          additionalProperties: true
          description: Optional metadata key-value pairs.
  securitySchemes:
    clientSdkKey:
      type: apiKey
      in: header
      name: statsig-api-key
      description: Client-SDK Key that is safe to embed in mobile apps and front-end web applications. Created in Project Settings > API Keys tab.
externalDocs:
  description: Statsig Client SDK Documentation
  url: https://docs.statsig.com/client/introduction