openapi: 3.1.0 info: title: Statsig Client SDK 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 externalDocs: description: Statsig Client SDK Documentation url: https://docs.statsig.com/client/introduction servers: - url: https://api.statsig.com/v1 description: Statsig API Server tags: - name: Events description: >- Endpoints for logging custom events and exposure data from client-side applications. - name: Initialization description: >- Endpoints for initializing client SDKs with all evaluated feature gates, configs, experiments, and layers for a given user. security: - clientSdkKey: [] 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' /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: 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. 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. 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. 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.