HTTP API

Before you can start calling the server APIs you need to take care of the following steps first:

1. Create a free account on statsig.com
2. Get an API key from the admin console
3. Issue API requests

Step 1 - Create a free account on statsig.com

An account will let you use the Statsig Console, where you can manage all of your Feature Gates and Dynamic Configs. Note that you will be able to invite others to your Statsig Projects, so they can also interact with your gates and configs.

Step 2 - Get an API key from statsig.com

An API key is required in every API request. There are two different types of API keys:

• Server-side secret Key which should only be used from a secure server and never shipped on clients.
• Client-SDK Key which can be embedded inside mobile apps and front-end client web apps.

If you are in doubt, use the Client-SDK key.

Step 3 - Issue API request

Our API is built on top of HTTPS. You can authenticate via header statsig-api-key. All of our APIs use method POST, and you can set parameters by using a JSON object as the request data.

There are just a few primitives that you need to get going on your way. The APIs automatically log exposure whenever you call them and Statsig will use these exposure events to attribute downstream events to compute analytics lift.

Log an event

curl \
  --header "statsig-api-key: <YOUR-SDK-KEY>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"events": [{"user": { "userID": "42" }, "time": 1616826986211, "eventName": "test_api_event"}]}' \
  "https://events.statsigapi.net/v1/log_event"

Schema

// json
{
  events: [StatsigEvent];
}

// StatsigEvent - object
{
  eventName: string;
  value: number | string;
  time: string; // unix timestamp
  user: StatsigUser;
  metadata: Record<string, string>;
}

// StatsigUser - object
{
  userID: string;
  email?: string;
  ip?: string;
  userAgent?: string;
  country?: string;
  locale?: string;
  appVersion?: string;
  custom?: Record<
    string,
    string | number | boolean | Array<string> | undefined
  >;
  privateAttributes?: Record<
    string,
    string | number | boolean | Array<string> | undefined
  >;
  customIDs?: Record<string, string>;
  statsigEnvironment: {
    tier: string
  };
};

Response: {"success":true}, status 202

Log an event with custom environment

Useful when you are operating in multiple environments like dev, staging, production.

curl \
  --header "statsig-api-key: <YOUR-SDK-KEY>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"events": [{"user": { "userID": "42", "statsigEnvironment": {"tier": "staging"} }, "time": 1616826986211, "eventName": "test_api_event"}]}' \
  "https://events.statsigapi.net/v1/log_event"

Response: {"success":true}

Check a Feature Gate

curl \
  --header "statsig-api-key: <YOUR-SDK-KEY>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"user": { "userID": "42" },"gateName":"<YOUR-GATE-NAME>"}' \
  "https://api.statsig.com/v1/check_gate"

Response: {"name":"YOUR-GATE-NAME","value":false,"rule_id":"123","group_name":"group123"}

Get a Dynamic Config value

curl \
  --header "statsig-api-key: <YOUR-SDK-KEY>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"user": { "userID": "42" },"configName":"<YOUR-CONFIG-NAME>"}' \
  "https://api.statsig.com/v1/get_config"

Response: {"name":"YOUR-CONFIG-NAME","value":{"a":1,"b":2},"group":"123","rule_id":"123","group_name":"group123"}

Fetch Experiment Config

Getting an experiment config is similar to fetching a dynamic configuration. The system will automatically log the right exposure based on the name of the config.

curl \
  --header "statsig-api-key: <YOUR-SDK-KEY>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"user": { "userID": "42" },"configName":"<YOUR-EXPERIMENT-NAME>"}' \
  "https://api.statsig.com/v1/get_config"

Response: {"name":"YOUR-EXPERIMENT-NAME","value":{"color":"blue","shape":"circle"},"group":"123","rule_id":"123","group_name":"group123}

Fetch Layer Value

The system will automatically log the right exposure based on the name of the config.

curl \
  --header "statsig-api-key: <YOUR-SDK-KEY>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"user": { "userID": "42" },"layerName":"<YOUR-LAYER-NAME>"}' \
  "https://statsigapi.net/v1/get_layer"

Response: {"name":"YOUR-LAYER-NAME","value":{"color":"blue","shape":"circle"},"ruleID":"2OZdhuDfq3w1UIHovUFRBM", "allocatedExperimentName": "a_experiment"}

Log an exposure event

You can log one or more exposure events with this API.

Experiments

// Experiment Exposure Events
// See https://docs.statsig.com/client/concepts/user for full list of user fields
user: object, // must have a userID or a customID to match with event data.
experimentName: string,
group: string,
time?: number | string, // unix timestamp, optional (request time used if not set)

For each exposure object, the "group" parameter should match the name of your Test Group in your experiment config. [

example experiment exposure

curl \
  --header "statsig-api-key: <YOUR-SDK-KEY>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"exposures": [{"user": {"userID": "user_id_12345"}, "experimentName": "analytics_only_experiment", "group": "Daily Deals"}]}' \
  "https://events.statsigapi.net/v1/log_custom_exposure"

Gates

// Gate Exposure Events
user: object, // must have a userID or a customID to match with event data.
gateName: string,
group: string,
passes: boolean,
time?: number | string, // unix timestamp, optional (request time used if not set)

For each exposure object, the "group" parameter should match the name of your Rule in your gate config.

example gate exposure

curl \
  --header "statsig-api-key: <YOUR-SDK-KEY>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"exposures": [{"user": {"userID": "user_id_12345"}, "gateName": "saleBanner", "group": "Controls Access", "passes": true}]}' \
  "https://events.statsigapi.net/v1/log_custom_exposure"