Manage segments within a project. Segments define groups of users based on traits and rules for targeted flag delivery.
openapi: 3.1.0
info:
title: Flagsmith Admin Environments Segments API
description: The Flagsmith Admin API allows developers to programmatically manage all aspects of their Flagsmith projects. Anything that can be done through the Flagsmith dashboard can also be accomplished via this API, including creating, updating, and deleting projects, environments, feature flags, segments, and users. It uses a secret Organisation API Token for authentication and provides a Swagger interface at api.flagsmith.com/api/v1/docs for interactive exploration.
version: '1.0'
contact:
name: Flagsmith Support
url: https://www.flagsmith.com/contact-us
termsOfService: https://www.flagsmith.com/terms-of-service
servers:
- url: https://api.flagsmith.com/api/v1
description: Flagsmith Production API
security:
- apiKeyAuth: []
tags:
- name: Segments
description: Manage segments within a project. Segments define groups of users based on traits and rules for targeted flag delivery.
paths:
/projects/{project_id}/segments/:
get:
operationId: listSegments
summary: List segments for a project
description: Retrieves a list of all segments defined within a specific project. Segments define groups of users based on trait-based rules for targeted flag delivery.
tags:
- Segments
parameters:
- $ref: '#/components/parameters/ProjectId'
responses:
'200':
description: Successful response containing a list of segments
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedResponse'
'401':
description: Unauthorized - invalid or missing API token
'404':
description: Project not found
post:
operationId: createSegment
summary: Create a segment
description: Creates a new segment within a project. Segments define groups of users based on trait-based rules and conditions for targeted feature flag delivery.
tags:
- Segments
parameters:
- $ref: '#/components/parameters/ProjectId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentInput'
responses:
'201':
description: Segment created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Segment'
'400':
description: Bad request - validation error
'401':
description: Unauthorized - invalid or missing API token
'404':
description: Project not found
/projects/{project_id}/segments/{segment_id}/:
get:
operationId: getSegment
summary: Get a segment
description: Retrieves the details of a specific segment by its ID within a project, including its rules and conditions.
tags:
- Segments
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/SegmentId'
responses:
'200':
description: Successful response containing the segment details
content:
application/json:
schema:
$ref: '#/components/schemas/Segment'
'401':
description: Unauthorized - invalid or missing API token
'404':
description: Segment or project not found
put:
operationId: updateSegment
summary: Update a segment
description: Updates the details of an existing segment including its name, description, and rules.
tags:
- Segments
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/SegmentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentInput'
responses:
'200':
description: Segment updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Segment'
'400':
description: Bad request - validation error
'401':
description: Unauthorized - invalid or missing API token
'404':
description: Segment or project not found
delete:
operationId: deleteSegment
summary: Delete a segment
description: Permanently deletes a segment from a project. Any segment overrides associated with this segment will also be removed. This action cannot be undone.
tags:
- Segments
parameters:
- $ref: '#/components/parameters/ProjectId'
- $ref: '#/components/parameters/SegmentId'
responses:
'204':
description: Segment deleted successfully
'401':
description: Unauthorized - invalid or missing API token
'404':
description: Segment or project not found
components:
schemas:
Segment:
type: object
description: A segment defines a group of users based on trait-based rules for targeted feature flag delivery.
properties:
id:
type: integer
description: The unique identifier for this segment
name:
type: string
description: The name of the segment
description:
type: string
nullable: true
description: A description of the segment
project:
type: integer
description: The ID of the project this segment belongs to
rules:
type: array
description: The rules that define segment membership
items:
$ref: '#/components/schemas/SegmentRule'
SegmentInput:
type: object
description: Input object for creating or updating a segment
required:
- name
- project
- rules
properties:
name:
type: string
description: The name of the segment
description:
type: string
nullable: true
description: A description of the segment
project:
type: integer
description: The ID of the project
rules:
type: array
description: The rules that define segment membership
items:
$ref: '#/components/schemas/SegmentRule'
PaginatedResponse:
type: object
description: A paginated response wrapper containing the results count and navigation links.
properties:
count:
type: integer
description: The total number of results
next:
type: string
nullable: true
format: uri
description: URL to the next page of results
previous:
type: string
nullable: true
format: uri
description: URL to the previous page of results
results:
type: array
description: The array of result objects for this page
items:
type: object
SegmentRule:
type: object
description: A rule within a segment that defines conditions for membership. Rules can be combined with AND/OR logic.
properties:
type:
type: string
enum:
- ALL
- ANY
- NONE
description: The logical operator for combining conditions within this rule. ALL requires all conditions to match, ANY requires at least one, NONE requires none to match.
rules:
type: array
description: Nested sub-rules for complex logic
items:
$ref: '#/components/schemas/SegmentRule'
conditions:
type: array
description: The conditions that make up this rule
items:
$ref: '#/components/schemas/SegmentCondition'
SegmentCondition:
type: object
description: A condition within a segment rule that evaluates a trait against a value using an operator.
properties:
operator:
type: string
enum:
- EQUAL
- NOT_EQUAL
- GREATER_THAN
- GREATER_THAN_INCLUSIVE
- LESS_THAN
- LESS_THAN_INCLUSIVE
- CONTAINS
- NOT_CONTAINS
- REGEX
- PERCENTAGE_SPLIT
- IS_SET
- IS_NOT_SET
- IN
description: The comparison operator to use
property_:
type: string
description: The trait key to evaluate
value:
type: string
description: The value to compare against
parameters:
SegmentId:
name: segment_id
in: path
description: The unique identifier for the segment
required: true
schema:
type: integer
ProjectId:
name: project_id
in: path
description: The unique identifier for the project
required: true
schema:
type: integer
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: Authorization
description: A secret Organisation API Token prefixed with 'Api-Key'. For example, 'Api-Key your-token-here'. This token should never be exposed in client-side code.
externalDocs:
description: Flagsmith Admin API Documentation
url: https://docs.flagsmith.com/integrating-with-flagsmith/flagsmith-api-overview/admin-api