openapi: 3.1.0
info:
  title: Statsig Events API
  description: >-
    The Statsig Events API handles the ingestion of event data from both
    client and server SDKs. It receives exposure events, custom events, and
    diagnostic data at the events.statsigapi.net endpoint. This data powers
    Statsig's experimentation analysis, product analytics, and metric
    computations. The Events API is optimized for high-throughput data
    ingestion, processing over a trillion events daily with high reliability
    and low latency, enabling real-time experiment monitoring and metric
    updates.
  version: '1.0.0'
  contact:
    name: Statsig Support
    url: https://statsig.com/support
  termsOfService: https://statsig.com/terms
externalDocs:
  description: Statsig HTTP API Documentation
  url: https://docs.statsig.com/http-api/
servers:
  - url: https://events.statsigapi.net/v1
    description: Statsig Events Ingestion Server
tags:
  - name: Events
    description: >-
      Endpoints for ingesting exposure events, custom events, and diagnostic
      data from SDKs for experimentation analysis and product analytics.
  - name: Webhooks
    description: >-
      Endpoint for receiving event data from third-party applications via
      webhook integration.
security:
  - statsigApiKey: []
paths:
  /log_event:
    post:
      operationId: logEvent
      summary: Log events
      description: >-
        Ingests one or more events from SDKs for analytics and experiment
        analysis. This endpoint accepts batched events including exposure
        events automatically generated by SDKs during gate checks and
        experiment evaluations, custom events logged by applications, and
        diagnostic events for SDK health monitoring. Events are processed
        asynchronously for high throughput.
      tags:
        - Events
      parameters:
        - name: STATSIG-CLIENT-TIME
          in: header
          required: true
          schema:
            type: integer
            format: int64
          description: >-
            Timestamp in milliseconds since epoch from the sending client
            or server, used to normalize event timestamps and account for
            clock differences.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - events
              properties:
                events:
                  type: array
                  items:
                    $ref: '#/components/schemas/Event'
                  description: >-
                    An array of events to ingest. Events are processed in
                    batch for efficiency.
                statsigMetadata:
                  $ref: '#/components/schemas/StatsigMetadata'
      responses:
        '202':
          description: Events accepted for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: >-
                      Whether the events were successfully accepted for
                      processing.
        '400':
          description: Invalid request format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/event_webhook:
    post:
      operationId: receiveWebhookEvent
      summary: Receive webhook events
      description: >-
        Receives event data from third-party applications or external sources
        via webhook integration. This endpoint allows logging events to
        Statsig from external systems to provide additional insights to
        experiments and metrics. Events are validated and ingested into the
        same analytics pipeline as SDK events.
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - events
              properties:
                events:
                  type: array
                  items:
                    $ref: '#/components/schemas/Event'
                  description: >-
                    An array of events from the external source.
      responses:
        '202':
          description: Webhook events accepted for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: >-
                      Whether the events were successfully accepted.
        '400':
          description: Invalid request format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    statsigApiKey:
      type: apiKey
      in: header
      name: statsig-api-key
      description: >-
        API key for authentication. Server Secret Keys or Client-SDK Keys
        are accepted depending on the event source.
  schemas:
    Event:
      type: object
      description: >-
        An event object representing an exposure, custom event, or diagnostic
        event for ingestion.
      required:
        - user
        - eventName
        - time
      properties:
        user:
          type: object
          description: >-
            The user associated with the event.
          properties:
            userID:
              type: string
              description: >-
                A unique identifier for the user.
            email:
              type: string
              format: email
              description: >-
                The user email address.
            custom:
              type: object
              additionalProperties: true
              description: >-
                Custom properties for the user.
            customIDs:
              type: object
              additionalProperties:
                type: string
              description: >-
                Custom identifier mappings.
        eventName:
          type: string
          description: >-
            The name of the event. Exposure events use the format
            statsig::gate_exposure or statsig::config_exposure. Custom
            events use application-defined names.
        time:
          type: integer
          format: int64
          description: >-
            Timestamp of the event in milliseconds since epoch.
        value:
          oneOf:
            - type: string
            - type: number
          description: >-
            An optional value associated with the event, such as revenue
            amount or duration.
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Optional metadata key-value pairs providing additional context
            for the event.
    StatsigMetadata:
      type: object
      description: >-
        Metadata about the SDK sending the events, used for attribution
        and diagnostics.
      properties:
        sdkType:
          type: string
          description: >-
            The type of SDK (e.g., js-client, py-server, react-native).
        sdkVersion:
          type: string
          description: >-
            The version of the SDK.
        sessionID:
          type: string
          description: >-
            The session identifier for client-side SDKs.
        stableID:
          type: string
          description: >-
            A stable device identifier for anonymous users.
    Error:
      type: object
      description: >-
        An error response from the Events API.
      properties:
        message:
          type: string
          description: >-
            A human-readable error message.
        status:
          type: integer
          description: >-
            The HTTP status code.
  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.