Segments
Manage workspace-scoped STANDARD, LARGE, and RULE_BASED segment metadata and lifecycle.
Returns a paginated list of Segments of one kind. segment_type is required (400 if omitted). Defaults to active segments (status defaults to [ACTIVE]). More than one status returns 400. Sorted by name ascending.
Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.
Harness account identifier. Required on all endpoints.
{{accountId}}Pattern: ^[-_A-Za-z0-9]+$Harness organization identifier.
defaultPattern: ^[-_A-Za-z0-9]+$Harness project identifier.
my_projectPattern: ^[-_A-Za-z0-9]+$Number of items to return per page. Defaults to 100, maximum 100.
100Example: 100Number of items to skip before the first returned result. Defaults to 0.
0Example: 0Kind of segment (STANDARD, LARGE, or RULE_BASED). Distinct from resource type
(SEGMENT).
STANDARDPossible values: OK — paginated list of segments returned.
Paginated list of Segments matching the query.
The page size used for this response.
100The number of items skipped before the first result.
0Total number of segments matching the query.
42Bad Request — validation errors or invalid state transition.
Unauthorized — the request is missing a valid API key, or the key has expired.
Forbidden — the caller is authenticated but not permitted to perform this operation.
Returned when the API can deny the operation without leaking whether a resource exists,
such as create, or write operations where the caller can already read the resource. When
returning 403 would reveal resource existence, the API returns 404 instead.
Environment-scoped mutations that require approval also return 403.
Too Many Requests — the caller has exceeded the rate limit for this endpoint.
Internal Server Error — an unexpected error occurred while processing the request.
GET /fme/api/v4/segments?account_id={{accountId}}&organization_identifier=default&project_identifier=my_project&segment_type=STANDARD HTTP/1.1
Host: app.harness.io
x-api-key: YOUR_API_KEY
Accept: */*
{
"data": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"name": "power-users",
"description": "Users with elevated privileges",
"trafficType": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
"name": "user"
},
"createdAt": "2025-06-01T12:00:00Z",
"status": "ACTIVE",
"tags": [
{
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad322",
"name": "backend"
}
],
"owners": [
{
"id": "xM5qi75eQYmdgJYfwNoHEQ",
"type": "USER",
"name": "Alice Example",
"email": "alice@example.com"
},
{
"id": "VP5X_K9mTqR2nLw8sYcHdA",
"type": "GROUP",
"name": "platform-team"
}
],
"segmentType": "STANDARD"
}
],
"limit": 100,
"offset": 0,
"totalCount": 42
}Creates a Segment. JSON segmentType is required. Creating RULE_BASED when the account cannot use rule-based segments returns 400.
Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.
Harness account identifier. Required on all endpoints.
{{accountId}}Pattern: ^[-_A-Za-z0-9]+$Harness organization identifier.
defaultPattern: ^[-_A-Za-z0-9]+$Harness project identifier.
my_projectPattern: ^[-_A-Za-z0-9]+$Request body for creating a Segment. Same fields for every segmentType.
Unique among active STANDARD and LARGE names in the project. Immutable after creation. If rule-based segments are enabled for the account, the name must also be unique against active RULE_BASED names.
power-usersPattern: ^[A-Za-z][-_A-Za-z0-9]*$Human-readable description of this segment.
Users with elevated privilegesTraffic type used to bucket users, identified by its name (for example user or
account). Immutable after creation.
userKind of segment (STANDARD, LARGE, or RULE_BASED). Distinct from resource type
(SEGMENT).
STANDARDPossible values: Created — the segment was successfully created.
Mutation response (create, update): entity plus OPA governance.
Bad Request — validation errors or invalid state transition.
Unauthorized — the request is missing a valid API key, or the key has expired.
Forbidden — the caller is authenticated but not permitted to perform this operation.
Returned when the API can deny the operation without leaking whether a resource exists,
such as create, or write operations where the caller can already read the resource. When
returning 403 would reveal resource existence, the API returns 404 instead.
Environment-scoped mutations that require approval also return 403.
Conflict — a resource with this identifier already exists, the operation conflicts with an
open change request, or the resource cannot be deleted/archived while dependents still
exist. Discriminate with errorType: resourceAlreadyExists, pendingChangeConflict, or
hasDependents. For hasDependents, detail is the archiver message when one is
available; otherwise Resource has active dependents.
Unprocessable Content — OPA governance policy evaluation returned ERROR (governanceError).
Each failing policy is listed in the errors array.
Too Many Requests — the caller has exceeded the rate limit for this endpoint.
Internal Server Error — an unexpected error occurred while processing the request.
POST /fme/api/v4/segments?account_id={{accountId}}&organization_identifier=default&project_identifier=my_project HTTP/1.1
Host: app.harness.io
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 198
{
"name": "power-users",
"description": "Users with elevated privileges",
"trafficType": "user",
"segmentType": "STANDARD",
"tags": [
{
"name": "backend"
}
],
"owners": [
{
"type": "USER",
"email": "alice@example.com"
}
]
}{
"entity": {
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"name": "power-users",
"description": "Users with elevated privileges",
"trafficType": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
"name": "user"
},
"createdAt": "2025-06-01T12:00:00Z",
"status": "ACTIVE",
"tags": [
{
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad322",
"name": "backend"
}
],
"owners": [
{
"id": "xM5qi75eQYmdgJYfwNoHEQ",
"type": "USER",
"name": "Alice Example",
"email": "alice@example.com"
},
{
"id": "VP5X_K9mTqR2nLw8sYcHdA",
"type": "GROUP",
"name": "platform-team"
}
],
"segmentType": "STANDARD"
},
"governance": {
"status": "PASS",
"details": []
}
}Active segment by name and segment_type. Omitting segment_type returns 400. ARCHIVED names return 404; use LIST with status=ARCHIVED to discover them.
Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.
The unique name of the segment within the project. Names must begin with a letter and
may contain letters, numbers, underscores, and hyphens. Use the same value that was
supplied as name when the segment was created. System-assigned ids are not accepted.
power-usersPattern: ^[A-Za-z][-_A-Za-z0-9]*$Kind of segment (STANDARD, LARGE, or RULE_BASED). Distinct from resource type
(SEGMENT).
STANDARDPossible values: Harness account identifier. Required on all endpoints.
{{accountId}}Pattern: ^[-_A-Za-z0-9]+$Harness organization identifier.
defaultPattern: ^[-_A-Za-z0-9]+$Harness project identifier.
my_projectPattern: ^[-_A-Za-z0-9]+$OK — segment returned.
A workspace-scoped Segment metadata entity (STANDARD, LARGE, or RULE_BASED).
Unique system-assigned identifier for the segment.
c3d4e5f6-a7b8-9012-cdef-123456789012Immutable after creation. Unique among active STANDARD and LARGE names in the project.
If rule-based segments are enabled for the account, the name must also be unique
against active RULE_BASED names. Resolve with path segment-name plus query
segment_type.
power-usersHuman-readable description of this segment.
Users with elevated privilegesISO-8601 timestamp when the segment was created.
2025-06-01T12:00:00ZLifecycle status of the segment.
ACTIVE— segment is live.ARCHIVED— segment is no longer active (soft-deleted).
ACTIVEPossible values: Kind of segment (STANDARD, LARGE, or RULE_BASED). Distinct from resource type
(SEGMENT).
STANDARDPossible values: Bad Request — validation errors or invalid state transition.
Unauthorized — the request is missing a valid API key, or the key has expired.
Not Found — the requested resource does not exist. Also returned when the caller lacks access to the resource (to avoid leaking resource existence).
Too Many Requests — the caller has exceeded the rate limit for this endpoint.
Internal Server Error — an unexpected error occurred while processing the request.
GET /fme/api/v4/segments/{segment-name}?segment_type=STANDARD&account_id={{accountId}}&organization_identifier=default&project_identifier=my_project HTTP/1.1
Host: app.harness.io
x-api-key: YOUR_API_KEY
Accept: */*
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"name": "power-users",
"description": "Users with elevated privileges",
"trafficType": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
"name": "user"
},
"createdAt": "2025-06-01T12:00:00Z",
"status": "ACTIVE",
"tags": [
{
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad322",
"name": "backend"
}
],
"owners": [
{
"id": "xM5qi75eQYmdgJYfwNoHEQ",
"type": "USER",
"name": "Alice Example",
"email": "alice@example.com"
},
{
"id": "VP5X_K9mTqR2nLw8sYcHdA",
"type": "GROUP",
"name": "platform-team"
}
],
"segmentType": "STANDARD"
}Archives a Segment of the given segment_type (400 if omitted). Returns the OPA governance result for the operation. Already archived or missing names return 404. Active dependents return 409 (hasDependents).
Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.
The unique name of the segment within the project. Names must begin with a letter and
may contain letters, numbers, underscores, and hyphens. Use the same value that was
supplied as name when the segment was created. System-assigned ids are not accepted.
power-usersPattern: ^[A-Za-z][-_A-Za-z0-9]*$Kind of segment (STANDARD, LARGE, or RULE_BASED). Distinct from resource type
(SEGMENT).
STANDARDPossible values: Harness account identifier. Required on all endpoints.
{{accountId}}Pattern: ^[-_A-Za-z0-9]+$Harness organization identifier.
defaultPattern: ^[-_A-Za-z0-9]+$Harness project identifier.
my_projectPattern: ^[-_A-Za-z0-9]+$OK — segment deleted. Returns the governance result.
Response envelope for delete operations. Contains only the OPA governance result — no entity is returned. Shared by all FME resources so delete responses are consistent.
Bad Request — validation errors or invalid state transition.
Unauthorized — the request is missing a valid API key, or the key has expired.
Forbidden — the caller is authenticated but not permitted to perform this operation.
Returned when the API can deny the operation without leaking whether a resource exists,
such as create, or write operations where the caller can already read the resource. When
returning 403 would reveal resource existence, the API returns 404 instead.
Environment-scoped mutations that require approval also return 403.
Not Found — the requested resource does not exist. Also returned when the caller lacks access to the resource (to avoid leaking resource existence).
Conflict — a resource with this identifier already exists, the operation conflicts with an
open change request, or the resource cannot be deleted/archived while dependents still
exist. Discriminate with errorType: resourceAlreadyExists, pendingChangeConflict, or
hasDependents. For hasDependents, detail is the archiver message when one is
available; otherwise Resource has active dependents.
Unprocessable Content — OPA governance policy evaluation returned ERROR (governanceError).
Each failing policy is listed in the errors array.
Too Many Requests — the caller has exceeded the rate limit for this endpoint.
Internal Server Error — an unexpected error occurred while processing the request.
DELETE /fme/api/v4/segments/{segment-name}?segment_type=STANDARD&account_id={{accountId}}&organization_identifier=default&project_identifier=my_project HTTP/1.1
Host: app.harness.io
x-api-key: YOUR_API_KEY
Accept: */*
{
"governance": {
"status": "PASS",
"details": []
}
}Partially updates a Segment (RFC 7396). Omit = keep; JSON null clears description; null or [] clears tags/owners. segment_type is required (400 if omitted). Already-archived segments return 404. segmentType is not patchable.
Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.
The unique name of the segment within the project. Names must begin with a letter and
may contain letters, numbers, underscores, and hyphens. Use the same value that was
supplied as name when the segment was created. System-assigned ids are not accepted.
power-usersPattern: ^[A-Za-z][-_A-Za-z0-9]*$Kind of segment (STANDARD, LARGE, or RULE_BASED). Distinct from resource type
(SEGMENT).
STANDARDPossible values: Harness account identifier. Required on all endpoints.
{{accountId}}Pattern: ^[-_A-Za-z0-9]+$Harness organization identifier.
defaultPattern: ^[-_A-Za-z0-9]+$Harness project identifier.
my_projectPattern: ^[-_A-Za-z0-9]+$JSON Merge Patch body (RFC 7396) for updating a Segment. All fields are optional. Omit a
field to leave it unchanged; send JSON null to clear description, or null/[] to clear
tags/owners. Present array fields replace the list in full. Kind is selected by query
segment_type. segmentType is not patchable. Unknown properties return 400.
Updated human-readable description.
Updated segment descriptionOK — segment updated.
Mutation response (create, update): entity plus OPA governance.
Bad Request — validation errors or invalid state transition.
Unauthorized — the request is missing a valid API key, or the key has expired.
Forbidden — the caller is authenticated but not permitted to perform this operation.
Returned when the API can deny the operation without leaking whether a resource exists,
such as create, or write operations where the caller can already read the resource. When
returning 403 would reveal resource existence, the API returns 404 instead.
Environment-scoped mutations that require approval also return 403.
Not Found — the requested resource does not exist. Also returned when the caller lacks access to the resource (to avoid leaking resource existence).
Unprocessable Content — OPA governance policy evaluation returned ERROR (governanceError).
Each failing policy is listed in the errors array.
Too Many Requests — the caller has exceeded the rate limit for this endpoint.
Internal Server Error — an unexpected error occurred while processing the request.
PATCH /fme/api/v4/segments/{segment-name}?segment_type=STANDARD&account_id={{accountId}}&organization_identifier=default&project_identifier=my_project HTTP/1.1
Host: app.harness.io
x-api-key: YOUR_API_KEY
Content-Type: application/merge-patch+json
Accept: */*
Content-Length: 130
{
"description": "Updated segment description",
"tags": [
{
"name": "backend"
}
],
"owners": [
{
"type": "GROUP",
"identifier": "platform-team"
}
]
}{
"entity": {
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"name": "power-users",
"description": "Users with elevated privileges",
"trafficType": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
"name": "user"
},
"createdAt": "2025-06-01T12:00:00Z",
"status": "ACTIVE",
"tags": [
{
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad322",
"name": "backend"
}
],
"owners": [
{
"id": "xM5qi75eQYmdgJYfwNoHEQ",
"type": "USER",
"name": "Alice Example",
"email": "alice@example.com"
},
{
"id": "VP5X_K9mTqR2nLw8sYcHdA",
"type": "GROUP",
"name": "platform-team"
}
],
"segmentType": "STANDARD"
},
"governance": {
"status": "PASS",
"details": []
}
}Last updated
Was this helpful?