openapi: 3.1.0 info: title: Statsig HTTP API description: >- The Statsig HTTP API allows developers to evaluate feature gates, dynamic configs, and experiments for users via server-side HTTP requests. It provides endpoints for checking gate values, fetching configuration data, and logging custom events. All requests use the POST method with JSON request bodies and require authentication via the statsig-api-key header. While Statsig recommends using their official SDKs for most use cases, the HTTP API is available for environments where an SDK is not available or when direct HTTP integration is preferred. version: '1.0.0' contact: name: Statsig Support url: https://statsig.com/support termsOfService: https://statsig.com/terms externalDocs: description: Statsig HTTP API Documentation url: https://docs.statsig.com/http-api/ servers: - url: https://api.statsig.com/v1 description: Statsig API Server tags: - name: Configuration description: >- Endpoints for downloading full project configuration specs for server-side local evaluation. - name: Dynamic Configs description: >- Endpoints for fetching dynamic configuration values for users, supporting both dynamic configs and experiments. - name: Events description: >- Endpoints for logging custom events and exposure data to Statsig for analytics and experiment analysis. - name: Experiments description: >- Endpoints for retrieving experiment configurations and group assignments for users. - name: Feature Gates description: >- Endpoints for evaluating feature gates for users, returning boolean pass/fail values along with rule identification. - name: Initialization description: >- Endpoints for initializing client SDKs with all evaluated gates, configs, experiments, and layers for a given user. - name: Layers description: >- Endpoints for fetching layer parameter values, enabling shared parameters across multiple experiments. security: - statsigApiKey: [] paths: /check_gate: post: operationId: checkGate summary: Check a feature gate description: >- Evaluates a single feature gate for the specified user and returns the boolean pass/fail result along with rule identification. Statsig automatically logs an exposure event for the gate check. tags: - Feature Gates requestBody: required: true content: application/json: schema: type: object required: - user - gateName properties: user: $ref: '#/components/schemas/StatsigUser' gateName: type: string description: >- The name of the feature gate to evaluate. responses: '200': description: Gate evaluation result content: application/json: schema: type: object properties: name: type: string description: >- The name of the gate that was evaluated. value: type: boolean description: >- Whether the user passes the gate. rule_id: type: string description: >- The identifier of the rule that was matched. group_name: type: string description: >- The name of the group the user was assigned to. '401': $ref: '#/components/responses/Unauthorized' /check_gate_multiple: post: operationId: checkGateMultiple summary: Check multiple feature gates description: >- Evaluates multiple feature gates for the specified user in a single request and returns the boolean pass/fail results for each gate. Statsig automatically logs exposure events for each gate check. tags: - Feature Gates requestBody: required: true content: application/json: schema: type: object required: - user - gateNames properties: user: $ref: '#/components/schemas/StatsigUser' gateNames: type: array items: type: string description: >- An array of feature gate names to evaluate. responses: '200': description: Multiple gate evaluation results content: application/json: schema: type: object properties: results: type: array items: type: object properties: name: type: string description: >- The name of the gate that was evaluated. value: type: boolean description: >- Whether the user passes the gate. rule_id: type: string description: >- The identifier of the rule that was matched. group_name: type: string description: >- The name of the group the user was assigned to. '401': $ref: '#/components/responses/Unauthorized' /get_config: post: operationId: getConfig summary: Get a dynamic config or experiment description: >- Fetches the configuration values for a dynamic config or experiment for the specified user. The system automatically determines whether the requested name refers to a dynamic config or an experiment. An exposure event is automatically logged. tags: - Dynamic Configs requestBody: required: true content: application/json: schema: type: object required: - user - configName properties: user: $ref: '#/components/schemas/StatsigUser' configName: type: string description: >- The name of the dynamic config or experiment to retrieve. responses: '200': description: Dynamic config or experiment values content: application/json: schema: type: object properties: name: type: string description: >- The name of the config that was retrieved. value: type: object description: >- The JSON object containing the configuration key-value pairs for this user. group: type: string description: >- The experiment group the user was assigned to, if applicable. rule_id: type: string description: >- The identifier of the rule that was matched. group_name: type: string description: >- The name of the group the user was assigned to. '401': $ref: '#/components/responses/Unauthorized' /get_experiment: post: operationId: getExperiment summary: Get an experiment configuration description: >- Fetches the experiment configuration and group assignment for the specified user. This is functionally similar to get_config but specifically targets experiments. An exposure event is automatically logged for experiment analysis. tags: - Experiments requestBody: required: true content: application/json: schema: type: object required: - user - experimentName properties: user: $ref: '#/components/schemas/StatsigUser' experimentName: type: string description: >- The name of the experiment to retrieve. responses: '200': description: Experiment configuration and group assignment content: application/json: schema: type: object properties: name: type: string description: >- The name of the experiment. value: type: object description: >- The JSON object containing the experiment parameter values for this user. group: type: string description: >- The experiment group the user was assigned to. rule_id: type: string description: >- The identifier of the rule that was matched. group_name: type: string description: >- The name of the group the user was assigned to. '401': $ref: '#/components/responses/Unauthorized' /get_layer: post: operationId: getLayer summary: Get layer parameters description: >- Fetches parameter values from a layer for the specified user. Layers allow sharing parameters across multiple experiments. An exposure event is logged only when a specific parameter is accessed. tags: - Layers requestBody: required: true content: application/json: schema: type: object required: - user - layerName properties: user: $ref: '#/components/schemas/StatsigUser' layerName: type: string description: >- The name of the layer to retrieve. responses: '200': description: Layer parameter values content: application/json: schema: type: object properties: name: type: string description: >- The name of the layer. value: type: object description: >- The JSON object containing the layer parameter values for this user. rule_id: type: string description: >- The identifier of the rule that was matched. group_name: type: string description: >- The name of the group the user was assigned to. '401': $ref: '#/components/responses/Unauthorized' /initialize: post: operationId: initialize summary: Initialize client SDK description: >- Returns all evaluated gates, configs, experiments, and layers for a given user. This is the primary endpoint used by client SDKs for initialization. The response contains hashed names for security, and the client SDK decodes them locally. tags: - Initialization requestBody: required: true content: application/json: schema: type: object required: - user properties: user: $ref: '#/components/schemas/StatsigUser' responses: '200': description: Full set of evaluated configurations for the user content: application/json: schema: type: object properties: feature_gates: type: object description: >- A map of hashed gate names to their evaluation results. dynamic_configs: type: object description: >- A map of hashed config names to their evaluation results. layer_configs: type: object 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. '401': $ref: '#/components/responses/Unauthorized' /log_event: post: operationId: logEvent summary: Log custom events description: >- Logs one or more custom events to Statsig for analytics and experiment analysis. Events can include exposure events, custom events with values, and metadata. The STATSIG-CLIENT-TIME header is required to normalize timestamps. 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. 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. 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' /download_config_specs: post: operationId: downloadConfigSpecs summary: Download configuration specs description: >- Downloads the full project configuration for server-side local evaluation. This endpoint is used by server SDKs to retrieve all gate, config, experiment, and layer definitions for evaluating locally without per-request network calls. This enables sub-millisecond feature gate checks. tags: - Configuration requestBody: required: true content: application/json: schema: type: object properties: sinceTime: type: integer format: int64 description: >- Timestamp of the last successful download, used for incremental updates. responses: '200': description: Full project configuration specs content: application/json: schema: type: object properties: dynamic_configs: type: array items: type: object description: >- Array of dynamic config and experiment specifications. feature_gates: type: array items: type: object description: >- Array of feature gate specifications. layer_configs: type: array items: type: object description: >- Array of layer specifications. has_updates: type: boolean description: >- Whether the response contains updates since sinceTime. time: type: integer format: int64 description: >- Server timestamp of this configuration snapshot. '401': $ref: '#/components/responses/Unauthorized' components: securitySchemes: statsigApiKey: type: apiKey in: header name: statsig-api-key description: >- API key for authentication. Use a Server Secret Key for secure server-side requests or a Client-SDK Key for client-side applications. schemas: StatsigUser: type: object description: >- The user object representing the end user being evaluated. At minimum, a userID should be provided. Additional properties enable more sophisticated targeting. properties: userID: type: string description: >- A unique identifier for the user. email: type: string format: email description: >- The email address of the user, used for email-based targeting. ip: type: string description: >- The IP address of the user, used for IP-based targeting. userAgent: type: string description: >- The user agent string, used for browser or device targeting. country: type: string description: >- The two-letter country code of the user. locale: type: string description: >- The locale identifier for the user. appVersion: type: string description: >- The version of the application the user is using. custom: type: object additionalProperties: true description: >- Custom properties for the user, used for custom targeting rules. privateAttributes: type: object additionalProperties: true description: >- Private user attributes used for evaluation but stripped before logging to Statsig servers. customIDs: type: object additionalProperties: type: string description: >- Custom identifier mappings for the user, such as companyID or teamID. StatsigEvent: type: object description: >- An event object representing a custom event or exposure to log. required: - user - eventName - time properties: user: $ref: '#/components/schemas/StatsigUser' eventName: type: string description: >- The name of the event being logged. time: type: integer format: int64 description: >- The timestamp of the event 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 associated with the event. 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.