statsig Holdouts API

openapi: 3.2.0
info:
  title: Statsig Console Holdouts 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: Holdouts
  description: Manage holdout groups that exclude users from receiving specific features for measuring long-term impact.
paths:
  /holdouts:
    get:
      operationId: listHoldouts
      summary: List all holdouts
      description: Retrieves a list of all holdout groups in the project.
      tags:
      - Holdouts
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          description: List of holdouts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Holdout'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createHoldout
      summary: Create a holdout
      description: Creates a new holdout group in the project for measuring long-term feature impact.
      tags:
      - Holdouts
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HoldoutCreate'
      responses:
        '201':
          description: Holdout created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Holdout'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
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.
    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:
    Holdout:
      type: object
      description: A holdout group that excludes users from specific features to measure long-term impact.
      properties:
        id:
          type: string
          description: The unique identifier of the holdout.
        name:
          type: string
          description: The name of the holdout.
        description:
          type: string
          description: A human-readable description.
        passPercentage:
          type: number
          minimum: 0
          maximum: 100
          description: The percentage of users in the holdout group.
        gateIDs:
          type: array
          items:
            type: string
          description: The gates affected by this holdout.
        isEnabled:
          type: boolean
          description: Whether the holdout is currently active.
    HoldoutCreate:
      type: object
      description: Request body for creating a new holdout group.
      required:
      - name
      properties:
        name:
          type: string
          description: The name of the holdout to create.
        description:
          type: string
          description: A human-readable description.
        passPercentage:
          type: number
          minimum: 0
          maximum: 100
          description: The percentage of users in the holdout group.
        gateIDs:
          type: array
          items:
            type: string
          description: The gates to include in the holdout.
  parameters:
    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/