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