Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Segments

Manage workspace-scoped STANDARD, LARGE, and RULE_BASED segment metadata and lifecycle.

List Segments

get
/v4/segments

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.

Authorizations
x-api-keystringRequired

Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.

Query parameters
account_idstring · max: 128Required

Harness account identifier. Required on all endpoints.

Example: {{accountId}}Pattern: ^[-_A-Za-z0-9]+$
organization_identifierstring · max: 128Required

Harness organization identifier.

Example: defaultPattern: ^[-_A-Za-z0-9]+$
project_identifierstring · max: 128Required

Harness project identifier.

Example: my_projectPattern: ^[-_A-Za-z0-9]+$
limitinteger · min: 1 · max: 100Optional

Number of items to return per page. Defaults to 100, maximum 100.

Default: 100Example: 100
offsetintegerOptional

Number of items to skip before the first returned result. Defaults to 0.

Default: 0Example: 0
segment_typestring · enumRequired

Kind of segment (STANDARD, LARGE, or RULE_BASED). Distinct from resource type (SEGMENT).

Example: STANDARDPossible values:
Responses
200

OK — paginated list of segments returned.

application/json

Paginated list of Segments matching the query.

limitintegerRequired

The page size used for this response.

Example: 100
offsetintegerRequired

The number of items skipped before the first result.

Example: 0
totalCountintegerRequired

Total number of segments matching the query.

Example: 42
get/v4/segments
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
}

Create a Segment

post
/v4/segments

Creates a Segment. JSON segmentType is required. Creating RULE_BASED when the account cannot use rule-based segments returns 400.

Authorizations
x-api-keystringRequired

Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.

Query parameters
account_idstring · max: 128Required

Harness account identifier. Required on all endpoints.

Example: {{accountId}}Pattern: ^[-_A-Za-z0-9]+$
organization_identifierstring · max: 128Required

Harness organization identifier.

Example: defaultPattern: ^[-_A-Za-z0-9]+$
project_identifierstring · max: 128Required

Harness project identifier.

Example: my_projectPattern: ^[-_A-Za-z0-9]+$
Body

Request body for creating a Segment. Same fields for every segmentType.

namestring · max: 100Required

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.

Example: power-usersPattern: ^[A-Za-z][-_A-Za-z0-9]*$
descriptionstringOptional

Human-readable description of this segment.

Example: Users with elevated privileges
trafficTypestringRequired

Traffic type used to bucket users, identified by its name (for example user or account). Immutable after creation.

Example: user
segmentTypestring · enumRequired

Kind of segment (STANDARD, LARGE, or RULE_BASED). Distinct from resource type (SEGMENT).

Example: STANDARDPossible values:
Responses
201

Created — the segment was successfully created.

application/json

Mutation response (create, update): entity plus OPA governance.

post/v4/segments
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": []
  }
}

Get a Segment

get
/v4/segments/{segment-name}

Active segment by name and segment_type. Omitting segment_type returns 400. ARCHIVED names return 404; use LIST with status=ARCHIVED to discover them.

Authorizations
x-api-keystringRequired

Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.

Path parameters
segment-namestring · max: 100Required

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.

Example: power-usersPattern: ^[A-Za-z][-_A-Za-z0-9]*$
Query parameters
segment_typestring · enumRequired

Kind of segment (STANDARD, LARGE, or RULE_BASED). Distinct from resource type (SEGMENT).

Example: STANDARDPossible values:
account_idstring · max: 128Required

Harness account identifier. Required on all endpoints.

Example: {{accountId}}Pattern: ^[-_A-Za-z0-9]+$
organization_identifierstring · max: 128Required

Harness organization identifier.

Example: defaultPattern: ^[-_A-Za-z0-9]+$
project_identifierstring · max: 128Required

Harness project identifier.

Example: my_projectPattern: ^[-_A-Za-z0-9]+$
Responses
200

OK — segment returned.

application/json

A workspace-scoped Segment metadata entity (STANDARD, LARGE, or RULE_BASED).

idstring · uuidRequired

Unique system-assigned identifier for the segment.

Example: c3d4e5f6-a7b8-9012-cdef-123456789012
namestringRequired

Immutable 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.

Example: power-users
descriptionstring · nullableOptional

Human-readable description of this segment.

Example: Users with elevated privileges
createdAtstring · date-timeRequired

ISO-8601 timestamp when the segment was created.

Example: 2025-06-01T12:00:00Z
statusstring · enumRequired

Lifecycle status of the segment.

  • ACTIVE — segment is live.
  • ARCHIVED — segment is no longer active (soft-deleted).
Example: ACTIVEPossible values:
segmentTypestring · enumRequired

Kind of segment (STANDARD, LARGE, or RULE_BASED). Distinct from resource type (SEGMENT).

Example: STANDARDPossible values:
get/v4/segments/{segment-name}
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"
}

Delete a Segment

delete
/v4/segments/{segment-name}

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).

Authorizations
x-api-keystringRequired

Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.

Path parameters
segment-namestring · max: 100Required

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.

Example: power-usersPattern: ^[A-Za-z][-_A-Za-z0-9]*$
Query parameters
segment_typestring · enumRequired

Kind of segment (STANDARD, LARGE, or RULE_BASED). Distinct from resource type (SEGMENT).

Example: STANDARDPossible values:
account_idstring · max: 128Required

Harness account identifier. Required on all endpoints.

Example: {{accountId}}Pattern: ^[-_A-Za-z0-9]+$
organization_identifierstring · max: 128Required

Harness organization identifier.

Example: defaultPattern: ^[-_A-Za-z0-9]+$
project_identifierstring · max: 128Required

Harness project identifier.

Example: my_projectPattern: ^[-_A-Za-z0-9]+$
Responses
200

OK — segment deleted. Returns the governance result.

application/json

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.

delete/v4/segments/{segment-name}
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": []
  }
}

Update a Segment (partial)

patch
/v4/segments/{segment-name}

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.

Authorizations
x-api-keystringRequired

Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.

Path parameters
segment-namestring · max: 100Required

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.

Example: power-usersPattern: ^[A-Za-z][-_A-Za-z0-9]*$
Query parameters
segment_typestring · enumRequired

Kind of segment (STANDARD, LARGE, or RULE_BASED). Distinct from resource type (SEGMENT).

Example: STANDARDPossible values:
account_idstring · max: 128Required

Harness account identifier. Required on all endpoints.

Example: {{accountId}}Pattern: ^[-_A-Za-z0-9]+$
organization_identifierstring · max: 128Required

Harness organization identifier.

Example: defaultPattern: ^[-_A-Za-z0-9]+$
project_identifierstring · max: 128Required

Harness project identifier.

Example: my_projectPattern: ^[-_A-Za-z0-9]+$
Body

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.

descriptionstring · nullableOptional

Updated human-readable description.

Example: Updated segment description
Responses
200

OK — segment updated.

application/json

Mutation response (create, update): entity plus OPA governance.

patch/v4/segments/{segment-name}
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?