Manage feature flag definitions in specific environments, including targeting rules, treatments, percentage rollouts, and default treatments.
openapi: 3.1.0
info:
title: Split Admin Feature Flag Definitions API
description: The Split Admin API is a REST API that enables programmatic management of workspaces (projects), environments, traffic types, attributes, users, groups, API keys, and change requests within the Split platform (now Harness Feature Management and Experimentation). The API uses resource-oriented URLs, returns JSON responses, and requires Admin API keys for authentication. All endpoints are prefixed with /internal/api/v2 on the api.split.io host.
version: '2.0'
contact:
name: Split Support
url: https://help.split.io
termsOfService: https://www.split.io/terms-of-service/
servers:
- url: https://api.split.io/internal/api/v2
description: Production Server
security:
- bearerAuth: []
tags:
- name: Feature Flag Definitions
description: Manage feature flag definitions in specific environments, including targeting rules, treatments, percentage rollouts, and default treatments.
paths:
/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:
schemas:
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
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
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
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'
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
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
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
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
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
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
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'
parameters:
limitParam:
name: limit
in: query
description: Maximum number of results to return per page
schema:
type: integer
minimum: 1
maximum: 200
default: 20
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
offsetParam:
name: offset
in: query
description: Number of results to skip for pagination
schema:
type: integer
minimum: 0
default: 0
workspaceIdParam:
name: workspaceId
in: path
required: true
description: The unique identifier of the workspace
schema:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Admin API key passed as a Bearer token in the Authorization header.
externalDocs:
description: Split Admin API Documentation
url: https://docs.split.io/reference/introduction