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.
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.