The Statsig Server SDK API provides endpoints that power Statsig's server-side SDKs for Node.js, Python, Java, Ruby, Go, .NET, and other backend languages. Server SDKs use Server Secret Keys and access the download_config_specs endpoint to retrieve the full project configuration for local evaluation. This enables sub-millisecond feature gate checks without per-request network calls.
openapi: 3.1.0
info:
title: Statsig Server SDK API
description: >-
The Statsig Server SDK API provides endpoints that power Statsig's
server-side SDKs for Node.js, Python, Java, Ruby, Go, .NET, and other
backend languages. Server SDKs use Server Secret Keys and access the
download_config_specs endpoint to retrieve the full project configuration
for local evaluation. This enables sub-millisecond feature gate checks
without per-request network calls. The server SDKs also use the log_event
endpoint for sending exposure and custom event data back to Statsig for
analytics and experiment analysis.
version: '1.0.0'
contact:
name: Statsig Support
url: https://statsig.com/support
termsOfService: https://statsig.com/terms
externalDocs:
description: Statsig Server SDK Documentation
url: https://docs.statsig.com/server/introduction
servers:
- url: https://api.statsig.com/v1
description: Statsig API Server
tags:
- name: Configuration
description: >-
Endpoints for downloading full project configuration specs that enable
server-side local evaluation of gates, configs, experiments, and layers.
- name: Events
description: >-
Endpoints for logging exposure and custom event data from server-side
SDKs back to Statsig for analytics and experiment analysis.
security:
- serverSecretKey: []
paths:
/download_config_specs:
post:
operationId: downloadConfigSpecs
summary: Download configuration specs
description: >-
Downloads the full project configuration for server-side local
evaluation. This endpoint is the primary mechanism used by server SDKs
to retrieve all gate, config, experiment, and layer definitions. The
downloaded specs enable sub-millisecond feature gate checks without
per-request network calls. Server SDKs periodically poll this endpoint
to stay up to date with configuration changes.
tags:
- Configuration
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
sinceTime:
type: integer
format: int64
description: >-
Timestamp of the last successful download in milliseconds
since epoch. Used for incremental updates to reduce
response size.
sdkType:
type: string
description: >-
The type of SDK making the request (e.g., py-server,
java-server, node-server).
sdkVersion:
type: string
description: >-
The version of the SDK making the request.
responses:
'200':
description: Full project configuration specs
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigSpecs'
'401':
$ref: '#/components/responses/Unauthorized'
/log_event:
post:
operationId: logServerEvent
summary: Log server events
description: >-
Logs one or more events from the server SDK to Statsig for analytics
and experiment analysis. Server SDKs batch exposure events from local
gate checks and custom events, then flush them periodically to this
endpoint. 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: >-
Server-side timestamp in milliseconds since epoch, used to
normalize event timestamps.
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, including exposure events from
local evaluation and custom events.
statsigMetadata:
type: object
properties:
sdkType:
type: string
description: >-
The type of SDK sending events.
sdkVersion:
type: string
description: >-
The version of the SDK.
description: >-
SDK metadata for attribution and diagnostics.
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:
serverSecretKey:
type: apiKey
in: header
name: statsig-api-key
description: >-
Server Secret Key for secure server-side API access. Must only be
used from trusted server environments and never exposed client-side.
schemas:
ConfigSpecs:
type: object
description: >-
The complete project configuration specs for server-side local
evaluation.
properties:
dynamic_configs:
type: array
items:
$ref: '#/components/schemas/ConfigSpec'
description: >-
Array of dynamic config and experiment specifications.
feature_gates:
type: array
items:
$ref: '#/components/schemas/ConfigSpec'
description: >-
Array of feature gate specifications.
layer_configs:
type: array
items:
$ref: '#/components/schemas/ConfigSpec'
description: >-
Array of layer specifications.
layers:
type: object
additionalProperties:
type: array
items:
type: string
description: >-
Map of layer names to their associated experiment names.
has_updates:
type: boolean
description: >-
Whether the response contains updates since sinceTime.
time:
type: integer
format: int64
description: >-
Server timestamp of this configuration snapshot.
ConfigSpec:
type: object
description: >-
A configuration specification for a gate, config, experiment, or layer
that enables local evaluation.
properties:
name:
type: string
description: >-
The name of the entity.
type:
type: string
enum:
- feature_gate
- dynamic_config
- experiment
- autotune
- layer
description: >-
The type of configuration entity.
salt:
type: string
description: >-
Salt value used for deterministic user assignment hashing.
enabled:
type: boolean
description: >-
Whether the entity is currently enabled.
rules:
type: array
items:
$ref: '#/components/schemas/RuleSpec'
description: >-
The evaluation rules for this entity.
defaultValue:
type: object
description: >-
The default value when no rules match.
RuleSpec:
type: object
description: >-
An evaluation rule specification used for local evaluation.
properties:
id:
type: string
description: >-
The unique identifier of the rule.
name:
type: string
description: >-
The name of the rule.
passPercentage:
type: number
minimum: 0
maximum: 100
description: >-
The percentage of matching users who pass the rule.
conditions:
type: array
items:
type: object
properties:
type:
type: string
description: >-
The type of condition.
targetValue:
description: >-
The target value to compare against.
operator:
type: string
description: >-
The comparison operator.
field:
type: string
description: >-
The user field to evaluate.
description: >-
The conditions that must be met for this rule.
returnValue:
type: object
description: >-
The value returned when this rule matches.
groupName:
type: string
description: >-
The group name assigned when this rule matches.
StatsigEvent:
type: object
description: >-
An event object for logging exposure or custom events.
required:
- user
- eventName
- time
properties:
user:
type: object
properties:
userID:
type: string
description: >-
A unique identifier for the user.
custom:
type: object
additionalProperties: true
description: >-
Custom properties for the user.
customIDs:
type: object
additionalProperties:
type: string
description: >-
Custom identifier mappings.
description: >-
The user associated with the event.
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.
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.