statsig Gates API

openapi: 3.2.0
info:
  title: Statsig Console Gates API
  description: The Statsig Console API enables developers to programmatically manage their Statsig project configuration. It supports full CRUD operations on feature gates, dynamic configs, experiments, segments, layers, holdouts, autotunes, metrics, keys, users, tags, target apps, audit logs, and other entities. The API requires a Console API Key and uses versioned endpoints with the STATSIG-API-VERSION header. It is designed for automation workflows such as bulk configuration edits, syncing definitions into Statsig from external systems, and integrating Statsig management into CI/CD pipelines.
  version: '20240601'
  contact:
    name: Statsig Support
    url: https://statsig.com/support
  termsOfService: https://statsig.com/terms
servers:
- url: https://statsigapi.net/console/v1
  description: Statsig Console API Server
security:
- consoleApiKey: []
tags:
- name: Gates
  description: Manage feature gates including creation, updates, rules, overrides, enabling, disabling, launching, and archiving.
paths:
  /gates:
    get:
      operationId: listGates
      summary: List all gates
      description: Retrieves a list of all feature gates in the project with their current status and configuration.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: List of feature gates
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Gate'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createGate
      summary: Create a gate
      description: Creates a new feature gate in the project with the specified configuration, rules, and targeting conditions.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GateCreate'
      responses:
        '201':
          description: Gate created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /gates/{id}:
    get:
      operationId: getGate
      summary: Get a gate
      description: Retrieves the full configuration of a specific feature gate including its rules, conditions, and overrides.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/GateId'
      responses:
        '200':
          description: Gate details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gate'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: partiallyUpdateGate
      summary: Partially update a gate
      description: Updates specific fields of a feature gate without replacing the entire configuration.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/GateId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GateUpdate'
      responses:
        '200':
          description: Gate updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteGate
      summary: Delete a gate
      description: Permanently deletes a feature gate from the project. This action cannot be undone.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/GateId'
      responses:
        '200':
          description: Gate deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /gates/{id}/enable:
    put:
      operationId: enableGate
      summary: Enable a gate
      description: Enables a feature gate so that its rules are actively evaluated for users.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/GateId'
      responses:
        '200':
          description: Gate enabled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gate'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /gates/{id}/disable:
    put:
      operationId: disableGate
      summary: Disable a gate
      description: Disables a feature gate so that it returns false for all users regardless of rules.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/GateId'
      responses:
        '200':
          description: Gate disabled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gate'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /gates/{id}/launch:
    put:
      operationId: launchGate
      summary: Launch a gate
      description: Launches a feature gate, indicating the feature has been fully rolled out and the gate can be cleaned up.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/GateId'
      responses:
        '200':
          description: Gate launched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gate'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /gates/{id}/archive:
    put:
      operationId: archiveGate
      summary: Archive a gate
      description: Archives a feature gate, removing it from active use while preserving its configuration for reference.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/GateId'
      responses:
        '200':
          description: Gate archived successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gate'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /gates/{id}/rules:
    get:
      operationId: listGateRules
      summary: List gate rules
      description: Retrieves all rules configured for a specific feature gate.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/GateId'
      responses:
        '200':
          description: List of gate rules
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Rule'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: addGateRule
      summary: Add a gate rule
      description: Adds a new targeting rule to a feature gate.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/GateId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Rule'
      responses:
        '201':
          description: Rule added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateGateRules
      summary: Update gate rules
      description: Replaces all rules for a feature gate with the provided set of rules.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/GateId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rules:
                  type: array
                  items:
                    $ref: '#/components/schemas/Rule'
      responses:
        '200':
          description: Rules updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /gates/{id}/rules/{ruleID}:
    delete:
      operationId: deleteGateRule
      summary: Delete a gate rule
      description: Removes a specific targeting rule from a feature gate.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/GateId'
      - name: ruleID
        in: path
        required: true
        schema:
          type: string
        description: The identifier of the rule to delete.
      responses:
        '200':
          description: Rule deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /gates/{id}/overrides:
    get:
      operationId: getGateOverrides
      summary: Get gate overrides
      description: Retrieves the user and ID overrides configured for a feature gate.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/GateId'
      responses:
        '200':
          description: Gate overrides
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Overrides'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: addGateOverrides
      summary: Add gate overrides
      description: Adds user or ID overrides to a feature gate for forcing specific evaluation results.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/GateId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Overrides'
      responses:
        '200':
          description: Overrides added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Overrides'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateGateOverrides
      summary: Update gate overrides
      description: Replaces all overrides for a feature gate with the provided set.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/GateId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Overrides'
      responses:
        '200':
          description: Overrides updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Overrides'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteGateOverrides
      summary: Delete gate overrides
      description: Removes all user and ID overrides from a feature gate.
      tags:
      - Gates
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/GateId'
      responses:
        '200':
          description: Overrides deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Error message describing what was wrong with the request.
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Error message indicating the resource was not found.
    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:
    Gate:
      type: object
      description: A feature gate configuration that controls access to features based on targeting rules and conditions.
      properties:
        id:
          type: string
          description: The unique identifier of the gate.
        name:
          type: string
          description: The name of the gate.
        description:
          type: string
          description: A human-readable description of the gate purpose.
        isEnabled:
          type: boolean
          description: Whether the gate is currently enabled and evaluating rules.
        status:
          type: string
          enum:
          - active
          - disabled
          - launched
          - archived
          description: The current lifecycle status of the gate.
        rules:
          type: array
          items:
            $ref: '#/components/schemas/Rule'
          description: The targeting rules for this gate.
        tags:
          type: array
          items:
            type: string
          description: Tags associated with the gate for organization.
        targetApps:
          type: array
          items:
            type: string
          description: Target applications this gate is scoped to.
        createdTime:
          type: integer
          format: int64
          description: Timestamp when the gate was created.
        lastModifiedTime:
          type: integer
          format: int64
          description: Timestamp when the gate was last modified.
    Overrides:
      type: object
      description: User and ID overrides for forcing specific evaluation results.
      properties:
        userOverrides:
          type: array
          items:
            type: object
            properties:
              userID:
                type: string
                description: The user ID to override.
              value:
                type: boolean
                description: The override value for this user.
          description: User-specific overrides by user ID.
        idOverrides:
          type: array
          items:
            type: object
            properties:
              ids:
                type: array
                items:
                  type: string
                description: The IDs to override.
              value:
                type: boolean
                description: The override value for these IDs.
          description: ID-based overrides for custom ID types.
    GateCreate:
      type: object
      description: Request body for creating a new feature gate.
      required:
      - name
      properties:
        name:
          type: string
          description: The name of the gate to create.
        description:
          type: string
          description: A human-readable description of the gate purpose.
        isEnabled:
          type: boolean
          description: Whether the gate should be enabled upon creation.
        rules:
          type: array
          items:
            $ref: '#/components/schemas/Rule'
          description: Initial targeting rules for the gate.
        tags:
          type: array
          items:
            type: string
          description: Tags to associate with the gate.
        targetApps:
          type: array
          items:
            type: string
          description: Target applications to scope this gate to.
    Condition:
      type: object
      description: A condition within a targeting rule that evaluates user properties against specified criteria.
      properties:
        type:
          type: string
          enum:
          - user_id
          - email
          - ip_address
          - country
          - app_version
          - custom_field
          - browser_name
          - browser_version
          - os_name
          - os_version
          - passes_gate
          - fails_gate
          - environment
          - passes_segment
          - fails_segment
          - time
          - unit_id
          description: The type of condition to evaluate.
        targetValue:
          description: The value or values to compare against.
        operator:
          type: string
          enum:
          - any
          - none
          - str_starts_with_any
          - str_ends_with_any
          - str_contains_any
          - str_contains_none
          - str_matches
          - gt
          - gte
          - lt
          - lte
          - version_gt
          - version_gte
          - version_lt
          - version_lte
          - before
          - after
          - true
          description: The comparison operator to use.
    Pagination:
      type: object
      description: Pagination metadata for list responses.
      properties:
        total:
          type: integer
          description: Total number of items available.
        page:
          type: integer
          description: Current page number.
        limit:
          type: integer
          description: Number of items per page.
        hasMore:
          type: boolean
          description: Whether more pages are available.
    GateUpdate:
      type: object
      description: Request body for partially updating a feature gate.
      properties:
        description:
          type: string
          description: Updated description of the gate purpose.
        isEnabled:
          type: boolean
          description: Whether the gate should be enabled.
        tags:
          type: array
          items:
            type: string
          description: Updated tags for the gate.
        targetApps:
          type: array
          items:
            type: string
          description: Updated target applications.
    Rule:
      type: object
      description: A targeting rule that defines conditions under which a gate passes or a config returns specific values.
      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 users matching conditions who pass the rule.
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/Condition'
          description: The conditions that must be met for this rule to apply.
        returnValue:
          type: object
          description: The value returned when this rule matches, for dynamic configs.
        environments:
          type: array
          items:
            type: string
          description: Environments where this rule is active.
  parameters:
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
      description: Page number for paginated results.
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
      description: Maximum number of items to return per page.
    GateId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The name or identifier of the feature gate.
    ApiVersion:
      name: STATSIG-API-VERSION
      in: header
      required: false
      schema:
        type: string
        default: '20240601'
      description: The Console API version. Currently the only version is 20240601.
  securitySchemes:
    consoleApiKey:
      type: apiKey
      in: header
      name: STATSIG-API-KEY
      description: Console API Key created in Project Settings > API Keys tab. Required for all Console API requests.
externalDocs:
  description: Statsig Console API Documentation
  url: https://docs.statsig.com/console-api/