The Split Feature Flag API provides endpoints for creating, editing, and deleting feature flags (splits) and their definitions within specific environments. Developers can use this API to define treatments, configure targeting rules, set percentage-based rollouts, and manage feature flag lifecycles programmatically.
openapi: 3.1.0
info:
title: Split Feature Flag API
description: >-
The Split Feature Flag API provides endpoints for creating, editing, and
deleting feature flags (splits) and their definitions within specific
environments. Developers can use this API to define treatments, configure
targeting rules, set percentage-based rollouts, and manage feature flag
lifecycles programmatically. It supports operations like creating feature
flag definitions in environments, updating targeting configurations, and
retrieving flag status across workspaces.
version: '2.0'
contact:
name: Split Support
url: https://help.split.io
termsOfService: https://www.split.io/terms-of-service/
externalDocs:
description: Split Feature Flag API Documentation
url: https://docs.split.io/reference/feature-flag-overview
servers:
- url: https://api.split.io/internal/api/v2
description: Production Server
tags:
- name: Feature Flag Definitions
description: >-
Manage feature flag definitions in specific environments, including
targeting rules, treatments, percentage rollouts, and default treatments.
- name: Feature Flags
description: >-
Create, retrieve, update, and delete feature flags (splits) within
workspaces. Feature flags represent the toggles used to control feature
rollouts.
security:
- bearerAuth: []
paths:
/splits/ws/{workspaceId}:
get:
operationId: listFeatureFlags
summary: List feature flags
description: >-
Retrieves all feature flags within the specified workspace. Returns
paginated results including flag name, description, traffic type,
creation time, and tags.
tags:
- Feature Flags
parameters:
- $ref: '#/components/parameters/workspaceIdParam'
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
- name: tags
in: query
description: Filter feature flags by tag names (comma-separated)
schema:
type: string
responses:
'200':
description: Successful response containing list of feature flags
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureFlagList'
'401':
description: Unauthorized - invalid or missing API key
'404':
description: Workspace not found
/splits/ws/{workspaceId}/trafficTypes/{trafficTypeId}:
post:
operationId: createFeatureFlag
summary: Create feature flag
description: >-
Creates a new feature flag within the specified workspace and traffic
type. The flag is created with default treatments of on and off. After
creation, a definition must be created in each environment where the
flag should be active.
tags:
- Feature Flags
parameters:
- $ref: '#/components/parameters/workspaceIdParam'
- name: trafficTypeId
in: path
required: true
description: >-
The identifier or name of the traffic type for the feature flag
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureFlagCreate'
responses:
'200':
description: Feature flag created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureFlag'
'400':
description: Invalid request body or feature flag name already exists
'401':
description: Unauthorized - invalid or missing API key
'404':
description: Workspace or traffic type not found
/splits/ws/{workspaceId}/{featureFlagName}:
get:
operationId: getFeatureFlag
summary: Get feature flag
description: >-
Retrieves a single feature flag by its name within the specified
workspace. Returns the flag metadata including name, description,
traffic type, creation time, and tags.
tags:
- Feature Flags
parameters:
- $ref: '#/components/parameters/workspaceIdParam'
- $ref: '#/components/parameters/featureFlagNameParam'
responses:
'200':
description: Successful response containing the feature flag
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureFlag'
'401':
description: Unauthorized - invalid or missing API key
'404':
description: Workspace or feature flag not found
put:
operationId: updateFeatureFlag
summary: Update feature flag
description: >-
Updates the metadata of an existing feature flag, such as its
description or tags.
tags:
- Feature Flags
parameters:
- $ref: '#/components/parameters/workspaceIdParam'
- $ref: '#/components/parameters/featureFlagNameParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureFlagUpdate'
responses:
'200':
description: Feature flag updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureFlag'
'400':
description: Invalid request body
'401':
description: Unauthorized - invalid or missing API key
'404':
description: Workspace or feature flag not found
delete:
operationId: deleteFeatureFlag
summary: Delete feature flag
description: >-
Deletes a feature flag from the specified workspace. The flag must first
have all its environment definitions removed before it can be deleted.
tags:
- Feature Flags
parameters:
- $ref: '#/components/parameters/workspaceIdParam'
- $ref: '#/components/parameters/featureFlagNameParam'
responses:
'200':
description: Feature flag deleted successfully
'401':
description: Unauthorized - invalid or missing API key
'404':
description: Workspace or feature flag not found
'409':
description: >-
Feature flag still has active definitions in one or more environments
/splits/ws/{workspaceId}/{featureFlagName}/environments/{environmentId}:
get:
operationId: getFeatureFlagDefinition
summary: Get feature flag definition in environment
description: >-
Retrieves the full definition of a feature flag in a specific
environment, including treatments, targeting rules, default treatment,
percentage rollout configuration, and kill status.
tags:
- Feature Flag Definitions
parameters:
- $ref: '#/components/parameters/workspaceIdParam'
- $ref: '#/components/parameters/featureFlagNameParam'
- $ref: '#/components/parameters/environmentIdParam'
responses:
'200':
description: >-
Successful response containing the feature flag definition
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureFlagDefinition'
'401':
description: Unauthorized - invalid or missing API key
'404':
description: >-
Workspace, feature flag, or environment not found
post:
operationId: createFeatureFlagDefinition
summary: Create feature flag definition in environment
description: >-
Creates a new definition for an existing feature flag in the specified
environment. This activates the flag in that environment with the
provided targeting rules and treatments.
tags:
- Feature Flag Definitions
parameters:
- $ref: '#/components/parameters/workspaceIdParam'
- $ref: '#/components/parameters/featureFlagNameParam'
- $ref: '#/components/parameters/environmentIdParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureFlagDefinitionCreate'
responses:
'200':
description: Feature flag definition created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureFlagDefinition'
'400':
description: Invalid request body
'401':
description: Unauthorized - invalid or missing API key
'404':
description: >-
Workspace, feature flag, or environment not found
patch:
operationId: updateFeatureFlagDefinition
summary: Update feature flag definition in environment
description: >-
Partially updates the definition of a feature flag in a specific
environment. Supports modifying targeting rules, percentage rollouts,
default treatment, and kill status.
tags:
- Feature Flag Definitions
parameters:
- $ref: '#/components/parameters/workspaceIdParam'
- $ref: '#/components/parameters/featureFlagNameParam'
- $ref: '#/components/parameters/environmentIdParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureFlagDefinitionUpdate'
responses:
'200':
description: Feature flag definition updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureFlagDefinition'
'400':
description: Invalid request body
'401':
description: Unauthorized - invalid or missing API key
'404':
description: >-
Workspace, feature flag, or environment not found
delete:
operationId: deleteFeatureFlagDefinition
summary: Delete feature flag definition in environment
description: >-
Removes the definition of a feature flag from the specified environment,
effectively deactivating the flag in that environment.
tags:
- Feature Flag Definitions
parameters:
- $ref: '#/components/parameters/workspaceIdParam'
- $ref: '#/components/parameters/featureFlagNameParam'
- $ref: '#/components/parameters/environmentIdParam'
responses:
'200':
description: Feature flag definition deleted successfully
'401':
description: Unauthorized - invalid or missing API key
'404':
description: >-
Workspace, feature flag, or environment not found
/splits/ws/{workspaceId}/environments/{environmentId}:
get:
operationId: listFeatureFlagDefinitionsInEnvironment
summary: List feature flag definitions in environment
description: >-
Retrieves all feature flag definitions within the specified environment
and workspace. Returns the targeting configuration, treatments, and
status of each flag.
tags:
- Feature Flag Definitions
parameters:
- $ref: '#/components/parameters/workspaceIdParam'
- $ref: '#/components/parameters/environmentIdParam'
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
responses:
'200':
description: >-
Successful response containing list of feature flag definitions
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureFlagDefinitionList'
'401':
description: Unauthorized - invalid or missing API key
'404':
description: Workspace or environment not found
/splits/ws/{workspaceId}/{featureFlagName}/environments/{environmentId}/kill:
put:
operationId: killFeatureFlag
summary: Kill feature flag in environment
description: >-
Kills a feature flag in the specified environment, forcing all
evaluations to return the default treatment. This is used as an
emergency shut-off mechanism.
tags:
- Feature Flag Definitions
parameters:
- $ref: '#/components/parameters/workspaceIdParam'
- $ref: '#/components/parameters/featureFlagNameParam'
- $ref: '#/components/parameters/environmentIdParam'
responses:
'200':
description: Feature flag killed successfully
'401':
description: Unauthorized - invalid or missing API key
'404':
description: >-
Workspace, feature flag, or environment not found
/splits/ws/{workspaceId}/{featureFlagName}/environments/{environmentId}/restore:
put:
operationId: restoreFeatureFlag
summary: Restore feature flag in environment
description: >-
Restores a previously killed feature flag in the specified environment,
resuming normal treatment evaluation based on targeting rules.
tags:
- Feature Flag Definitions
parameters:
- $ref: '#/components/parameters/workspaceIdParam'
- $ref: '#/components/parameters/featureFlagNameParam'
- $ref: '#/components/parameters/environmentIdParam'
responses:
'200':
description: Feature flag restored successfully
'401':
description: Unauthorized - invalid or missing API key
'404':
description: >-
Workspace, feature flag, or environment not found
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Admin API key passed as a Bearer token in the Authorization header.
parameters:
workspaceIdParam:
name: workspaceId
in: path
required: true
description: The unique identifier of the workspace
schema:
type: string
featureFlagNameParam:
name: featureFlagName
in: path
required: true
description: The name of the feature flag
schema:
type: string
environmentIdParam:
name: environmentId
in: path
required: true
description: The unique identifier or name of the environment
schema:
type: string
limitParam:
name: limit
in: query
description: Maximum number of results to return per page
schema:
type: integer
minimum: 1
maximum: 200
default: 20
offsetParam:
name: offset
in: query
description: Number of results to skip for pagination
schema:
type: integer
minimum: 0
default: 0
schemas:
FeatureFlag:
type: object
description: >-
A feature flag (split) representing a toggle used to control feature
rollouts and experimentation.
properties:
name:
type: string
description: Unique name of the feature flag
description:
type: string
description: Human-readable description of the feature flag
trafficType:
$ref: '#/components/schemas/TrafficType'
creationTime:
type: integer
format: int64
description: Unix timestamp of when the feature flag was created
tags:
type: array
description: Tags associated with the feature flag
items:
$ref: '#/components/schemas/Tag'
FeatureFlagList:
type: object
description: Paginated list of feature flags
properties:
objects:
type: array
items:
$ref: '#/components/schemas/FeatureFlag'
offset:
type: integer
description: Current offset in the result set
limit:
type: integer
description: Maximum number of results returned
totalCount:
type: integer
description: Total number of feature flags available
FeatureFlagCreate:
type: object
description: Request body for creating a new feature flag
required:
- name
properties:
name:
type: string
description: >-
Name of the feature flag. Must be unique within the workspace.
pattern: '^[a-zA-Z0-9_-]+$'
maxLength: 256
description:
type: string
description: Description of the feature flag
tags:
type: array
description: Tags to associate with the feature flag
items:
$ref: '#/components/schemas/Tag'
FeatureFlagUpdate:
type: object
description: Request body for updating a feature flag
properties:
description:
type: string
description: Updated description of the feature flag
tags:
type: array
description: Updated tags for the feature flag
items:
$ref: '#/components/schemas/Tag'
FeatureFlagDefinition:
type: object
description: >-
The full definition of a feature flag in a specific environment,
including treatments, targeting rules, and rollout configuration.
properties:
name:
type: string
description: Name of the feature flag
environment:
$ref: '#/components/schemas/EnvironmentRef'
trafficType:
$ref: '#/components/schemas/TrafficType'
killed:
type: boolean
description: >-
Whether the flag is killed, forcing all evaluations to return
the default treatment
treatments:
type: array
description: >-
List of possible treatments that this feature flag can return
items:
$ref: '#/components/schemas/Treatment'
defaultTreatment:
type: string
description: >-
The treatment returned when no targeting rules match or when
the flag is killed
baselineTreatment:
type: string
description: >-
The control treatment used as a baseline for experimentation
rules:
type: array
description: >-
Ordered list of targeting rules evaluated top to bottom. The
first matching rule determines the treatment.
items:
$ref: '#/components/schemas/TargetingRule'
defaultRule:
type: array
description: >-
The default rule applied when no targeting rules match. Defines
the percentage-based rollout for unmatched traffic.
items:
$ref: '#/components/schemas/Bucket'
trafficAllocation:
type: integer
description: >-
Percentage of traffic that is included in the feature flag
evaluation (0-100). Traffic outside this allocation receives
the default treatment.
minimum: 0
maximum: 100
lastModified:
type: integer
format: int64
description: Unix timestamp of the last modification
creationTime:
type: integer
format: int64
description: Unix timestamp of when the definition was created
FeatureFlagDefinitionList:
type: object
description: Paginated list of feature flag definitions
properties:
objects:
type: array
items:
$ref: '#/components/schemas/FeatureFlagDefinition'
offset:
type: integer
description: Current offset in the result set
limit:
type: integer
description: Maximum number of results returned
totalCount:
type: integer
description: Total number of definitions available
FeatureFlagDefinitionCreate:
type: object
description: >-
Request body for creating a feature flag definition in an environment
required:
- treatments
- defaultTreatment
- defaultRule
properties:
treatments:
type: array
description: List of treatments for this definition
items:
$ref: '#/components/schemas/Treatment'
defaultTreatment:
type: string
description: The default treatment for unmatched traffic
baselineTreatment:
type: string
description: The baseline treatment for experimentation
rules:
type: array
description: Targeting rules for the definition
items:
$ref: '#/components/schemas/TargetingRule'
defaultRule:
type: array
description: Default percentage-based rollout rule
items:
$ref: '#/components/schemas/Bucket'
trafficAllocation:
type: integer
description: Percentage of traffic included in evaluation
minimum: 0
maximum: 100
FeatureFlagDefinitionUpdate:
type: object
description: >-
Request body for partially updating a feature flag definition in an
environment. Only provided fields are updated.
properties:
treatments:
type: array
description: Updated list of treatments
items:
$ref: '#/components/schemas/Treatment'
defaultTreatment:
type: string
description: Updated default treatment
baselineTreatment:
type: string
description: Updated baseline treatment
rules:
type: array
description: Updated targeting rules
items:
$ref: '#/components/schemas/TargetingRule'
defaultRule:
type: array
description: Updated default percentage-based rollout rule
items:
$ref: '#/components/schemas/Bucket'
trafficAllocation:
type: integer
description: Updated traffic allocation percentage
minimum: 0
maximum: 100
comment:
type: string
description: Comment describing the update
Treatment:
type: object
description: >-
A treatment representing one of the possible values returned by a
feature flag evaluation.
required:
- name
properties:
name:
type: string
description: Name of the treatment (e.g., on, off, v1, v2)
description:
type: string
description: Description of what this treatment does
configurations:
type: string
description: >-
JSON string containing dynamic configuration associated with
this treatment
TargetingRule:
type: object
description: >-
A targeting rule that matches specific conditions and assigns
treatments to matching traffic.
properties:
condition:
$ref: '#/components/schemas/Condition'
buckets:
type: array
description: >-
Percentage-based distribution of treatments for traffic matching
this rule
items:
$ref: '#/components/schemas/Bucket'
Condition:
type: object
description: >-
A condition defining the matching criteria for a targeting rule.
properties:
combiner:
type: string
description: >-
Logical combiner for multiple matchers within this condition
enum:
- AND
matchers:
type: array
description: List of matchers that define the matching criteria
items:
$ref: '#/components/schemas/Matcher'
Matcher:
type: object
description: >-
A matcher defining a single matching criterion based on attributes,
segments, or key values.
properties:
type:
type: string
description: Type of matching to perform
enum:
- IN_SEGMENT
- WHITELIST
- ALL_KEYS
- EQUAL_TO
- GREATER_THAN_OR_EQUAL_TO
- LESS_THAN_OR_EQUAL_TO
- BETWEEN
- CONTAINS_STRING
- STARTS_WITH
- ENDS_WITH
- MATCHES_STRING
- IN_LIST_STRING
- EQUAL_TO_SET
- CONTAINS_ALL_OF_SET
- CONTAINS_ANY_OF_SET
- PART_OF_SET
- EQUAL_TO_BOOLEAN
- DEPENDS_ON
negate:
type: boolean
description: Whether to negate the matcher result
attribute:
type: string
description: >-
The attribute name to match against. Required for attribute-based
matchers.
strings:
type: array
description: String values used by string-based matchers
items:
type: string
number:
type: integer
description: Numeric value used by numeric matchers
date:
type: integer
format: int64
description: Unix timestamp value used by date-based matchers
between:
type: object
description: Range values for the BETWEEN matcher
properties:
from:
type: integer
description: Lower bound of the range
to:
type: integer
description: Upper bound of the range
depends:
type: object
description: Dependency configuration for the DEPENDS_ON matcher
properties:
splitName:
type: string
description: Name of the feature flag to depend on
treatments:
type: array
description: Treatments that must be returned by the dependency
items:
type: string
Bucket:
type: object
description: >-
A bucket defining the percentage of traffic assigned to a specific
treatment within a rule.
properties:
treatment:
type: string
description: Name of the treatment assigned to this bucket
size:
type: integer
description: Percentage of traffic allocated to this bucket (0-100)
minimum: 0
maximum: 100
TrafficType:
type: object
description: >-
A traffic type defining the kind of entity targeted by feature flags.
properties:
id:
type: string
description: Unique identifier for the traffic type
name:
type: string
description: Name of the traffic type
EnvironmentRef:
type: object
description: A reference to an environment
properties:
id:
type: string
description: Unique identifier of the environment
name:
type: string
description: Name of the environment
Tag:
type: object
description: A tag associated with a feature flag
properties:
name:
type: string
description: Name of the tag