Statsig Events API

openapi: 3.2.0
info:
  title: Statsig HTTP Events API
  description: The Statsig HTTP API allows developers to evaluate feature gates, dynamic configs, and experiments for users via server-side HTTP requests.
  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:
- statsigApiKey: []
tags:
- name: Events
  description: Endpoints for logging custom events and exposure data to Statsig for analytics and experiment analysis.
paths:
  /log_event:
    post:
      operationId: logEvent
      summary: Log custom events
      description: Logs one or more custom events to Statsig for analytics and experiment analysis. Events can include exposure events, custom events with values, and metadata. The STATSIG-CLIENT-TIME header is required to normalize timestamps.
      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.
      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.
      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:
  schemas:
    StatsigUser:
      type: object
      description: The user object representing the end user being evaluated. At minimum, a userID should be provided. Additional properties enable more sophisticated targeting.
      properties:
        userID:
          type: string
          description: A unique identifier for the user.
        email:
          type: string
          format: email
          description: The email address of the user, used for email-based targeting.
        ip:
          type: string
          description: The IP address of the user, used for IP-based targeting.
        userAgent:
          type: string
          description: The user agent string, used for browser or device targeting.
        country:
          type: string
          description: The two-letter country code of the user.
        locale:
          type: string
          description: The locale identifier for the user.
        appVersion:
          type: string
          description: The version of the application the user is using.
        custom:
          type: object
          additionalProperties: true
          description: Custom properties for the user, used for custom targeting rules.
        privateAttributes:
          type: object
          additionalProperties: true
          description: Private user attributes used for evaluation but stripped before logging to Statsig servers.
        customIDs:
          type: object
          additionalProperties:
            type: string
          description: Custom identifier mappings for the user, such as companyID or teamID.
    StatsigEvent:
      type: object
      description: An event object representing a custom event or exposure to log.
      required:
      - user
      - eventName
      - time
      properties:
        user:
          $ref: '#/components/schemas/StatsigUser'
        eventName:
          type: string
          description: The name of the event being logged.
        time:
          type: integer
          format: int64
          description: The timestamp of the event 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 associated with the event.
  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.
  securitySchemes:
    statsigApiKey:
      type: apiKey
      in: header
      name: statsig-api-key
      description: API key for authentication. Use a Server Secret Key for secure server-side requests or a Client-SDK Key for client-side applications.
externalDocs:
  description: Statsig HTTP API Documentation
  url: https://docs.statsig.com/http-api/