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.
  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.
  parameters:
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
      description: Maximum number of items to return per page.
    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.
    GateId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The name or identifier of the feature gate.
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
      description: Page number for paginated results.
  schemas:
    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.
    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.
    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.
    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.
  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/