openapi: 3.1.0
info:
  title: Statsig Client SDK Audit Logs Initialization 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: Initialization
  description: Endpoints for initializing client SDKs with all evaluated feature gates, configs, experiments, and layers for a given user.
paths:
  /initialize:
    post:
      operationId: initializeClient
      summary: Initialize client SDK
      description: Returns all evaluated gates, configs, experiments, and layers for a given user. This is the primary endpoint called during client SDK initialization. The response contains hashed entity names for security, and the client SDK decodes them locally. The response is optimized for client-side caching and includes a hash for detecting changes on subsequent requests.
      tags:
      - Initialization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - user
              properties:
                user:
                  $ref: '#/components/schemas/StatsigUser'
                hash:
                  type: string
                  description: Hash from a previous initialize response, used to detect changes and enable incremental updates.
                sinceTime:
                  type: integer
                  format: int64
                  description: Timestamp of the last successful initialization, used for incremental updates.
      responses:
        '200':
          description: Evaluated configurations for the user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitializeResponse'
        '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.
    InitializeResponse:
      type: object
      description: The response from the initialize endpoint containing all evaluated configurations for the user.
      properties:
        feature_gates:
          type: object
          additionalProperties:
            type: object
            properties:
              value:
                type: boolean
                description: Whether the user passes the gate.
              rule_id:
                type: string
                description: The matched rule identifier.
              secondary_exposures:
                type: array
                items:
                  type: object
                description: Secondary exposure data for nested gate evaluations.
          description: A map of hashed gate names to their evaluation results.
        dynamic_configs:
          type: object
          additionalProperties:
            type: object
            properties:
              value:
                type: object
                description: The config parameter values for this user.
              rule_id:
                type: string
                description: The matched rule identifier.
              secondary_exposures:
                type: array
                items:
                  type: object
                description: Secondary exposure data.
          description: A map of hashed config names to their evaluation results.
        layer_configs:
          type: object
          additionalProperties:
            type: object
            properties:
              value:
                type: object
                description: The layer parameter values.
              rule_id:
                type: string
                description: The matched rule identifier.
              explicit_parameters:
                type: array
                items:
                  type: string
                description: Parameters explicitly set by the active experiment.
          description: A map of hashed layer names to their evaluation results.
        has_updates:
          type: boolean
          description: Whether there are updates since the last initialization.
        time:
          type: integer
          format: int64
          description: Server timestamp of the evaluation.
        hash_used:
          type: string
          description: The hashing algorithm used for entity names.
  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