statsig Initialization API
Endpoints for initializing client SDKs with all evaluated feature gates, configs, experiments, and layers for a given user.
OpenAPI Specification
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