Skip to main content

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"

Response: {"success":true}

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}

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":"default"}

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":"default"}

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"}

Export Report

You can export your Pulse data via the console or using the following API. In addition to the first_exposures report type as shown below, you can also request a pulse_daily or unit_metrics_daily report types.

Note this API requires a server-side secret key.

curl \
--header "statsig-api-key: <YOUR-SERVER-SECRET-KEY>" \
--header "Content-Type: application/json" \
--request POST \
--data '{"type": "first_exposures" }' \
"https://api.statsig.com/v1/get_daily_report"

Response: { date: {date in PST of data} url: {url to download CSV for the specified type} }

Log an exposure event

You can log one or more exposure events with this API. For each exposure object, the "group" parameter should match the "Group Name" in your experiment.

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": "Control"}]}' \
"https://events.statsigapi.net/v1/log_custom_exposure"

Event inputs to this endpoint can have either of the two following forms:

// 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)
// 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)