Feature Flag Definitions
Manage environment-specific feature flag definitions (treatments, traffic allocation, targeting).
Returns a paginated list of active Feature Flag Definitions across all environments for the Feature Flag specified by feature_flag_name. Returns 404 if no Feature Flag with that name exists in the project.
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]+$The unique name of the feature flag whose definitions to list. System-assigned identifiers are not accepted.
my-new-flagPattern: ^[A-Za-z][-_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: 0OK — paginated list of feature flag definitions returned.
Paginated list of active Feature Flag Definitions.
The page size used for this response.
100The number of items skipped before the first result.
0Total number of active feature flag definitions matching the query.
8Bad 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).
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/feature-flag-definitions?account_id={{accountId}}&organization_identifier=default&project_identifier=my_project&feature_flag_name=my-new-flag HTTP/1.1
Host: app.harness.io
x-api-key: YOUR_API_KEY
Accept: */*
{
"data": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"featureFlag": {
"id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
"name": "my-new-flag"
},
"environment": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
"name": "Production"
},
"trafficType": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "user"
},
"isKilled": false,
"treatments": [
{
"name": "on",
"description": "The feature flag is on"
},
{
"name": "off",
"description": "The feature flag is off"
}
],
"defaultTreatment": "off",
"baselineTreatment": "off",
"trafficAllocation": 100,
"rules": [
{
"condition": {
"combiner": "AND",
"matchers": [
{
"type": "IN_LIST_STRING",
"negate": false,
"attribute": "country",
"strings": [
"US",
"CA"
]
}
]
},
"buckets": [
{
"treatment": "on",
"size": 75
},
{
"treatment": "off",
"size": 25
}
]
}
],
"defaultRule": [
{
"treatment": "off",
"size": 100
}
],
"flagSets": [
{
"id": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
],
"createdAt": "2025-06-01T12:00:00Z",
"impressions": {
"lastImpressionAt": "2025-06-15T09:30:00Z"
}
}
],
"limit": 100,
"offset": 0,
"totalCount": 8
}Requires environment_id as a query parameter. Kills the Feature Flag Definition for the specified feature flag in the specified environment. A killed definition serves the default treatment. Any pending change request for this definition is auto-rejected so the kill can proceed.
Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.
The unique name of the feature flag 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 flag was created. System-assigned ids are not accepted.
my-new-flagPattern: ^[A-Za-z][-_A-Za-z0-9]*$Harness account identifier. Required on all endpoints.
{{accountId}}Pattern: ^[-_A-Za-z0-9]+$Environment identifier. Scopes the request to a specific environment; combined with the resource name in the path it identifies a specific environment-scoped definition (e.g., a Feature Flag Definition or a Segment Definition).
ad2eb8f0-9c3a-11ed-873c-e234abaad319Pattern: ^[-_A-Za-z0-9]+$Harness organization identifier.
defaultPattern: ^[-_A-Za-z0-9]+$Harness project identifier.
my_projectPattern: ^[-_A-Za-z0-9]+$Optional metadata supplied when killing, restoring, or reallocating a feature flag definition.
Optional comment recorded with the action.
Disabling the feature during incident mitigation.Optional title recorded with the action.
Kill billing-experience in productionOK — feature flag definition killed.
Feature Flag Definition entity together with the OPA governance result.
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.
POST /fme/api/v4/feature-flag-definitions/{feature-flag-name}/kill?account_id={{accountId}}&environment_id=ad2eb8f0-9c3a-11ed-873c-e234abaad319&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: 111
{
"comment": "Disabling the feature during incident mitigation.",
"title": "Kill billing-experience in production"
}{
"entity": {
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"featureFlag": {
"id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
"name": "my-new-flag"
},
"environment": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
"name": "Production"
},
"trafficType": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "user"
},
"isKilled": false,
"treatments": [
{
"name": "on",
"description": "The feature flag is on"
},
{
"name": "off",
"description": "The feature flag is off"
}
],
"defaultTreatment": "off",
"baselineTreatment": "off",
"trafficAllocation": 100,
"rules": [
{
"condition": {
"combiner": "AND",
"matchers": [
{
"type": "IN_LIST_STRING",
"negate": false,
"attribute": "country",
"strings": [
"US",
"CA"
]
}
]
},
"buckets": [
{
"treatment": "on",
"size": 75
},
{
"treatment": "off",
"size": 25
}
]
}
],
"defaultRule": [
{
"treatment": "off",
"size": 100
}
],
"flagSets": [
{
"id": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
],
"createdAt": "2025-06-01T12:00:00Z",
"impressions": {
"lastImpressionAt": "2025-06-15T09:30:00Z"
}
},
"governance": {
"status": "PASS",
"details": []
}
}Requires environment_id as a query parameter. Restores the Feature Flag Definition for the specified feature flag in the specified environment after it was killed. Returns 409 when a pending change request already exists for this definition, 400 (invalidState) when the definition is not currently killed, and 403 when the environment requires approval.
Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.
The unique name of the feature flag 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 flag was created. System-assigned ids are not accepted.
my-new-flagPattern: ^[A-Za-z][-_A-Za-z0-9]*$Harness account identifier. Required on all endpoints.
{{accountId}}Pattern: ^[-_A-Za-z0-9]+$Environment identifier. Scopes the request to a specific environment; combined with the resource name in the path it identifies a specific environment-scoped definition (e.g., a Feature Flag Definition or a Segment Definition).
ad2eb8f0-9c3a-11ed-873c-e234abaad319Pattern: ^[-_A-Za-z0-9]+$Harness organization identifier.
defaultPattern: ^[-_A-Za-z0-9]+$Harness project identifier.
my_projectPattern: ^[-_A-Za-z0-9]+$Optional metadata supplied when killing, restoring, or reallocating a feature flag definition.
Optional comment recorded with the action.
Disabling the feature during incident mitigation.Optional title recorded with the action.
Kill billing-experience in productionOK — feature flag definition restored.
Feature Flag Definition entity together with the OPA governance result.
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.
POST /fme/api/v4/feature-flag-definitions/{feature-flag-name}/restore?account_id={{accountId}}&environment_id=ad2eb8f0-9c3a-11ed-873c-e234abaad319&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: 111
{
"comment": "Disabling the feature during incident mitigation.",
"title": "Kill billing-experience in production"
}{
"entity": {
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"featureFlag": {
"id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
"name": "my-new-flag"
},
"environment": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
"name": "Production"
},
"trafficType": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "user"
},
"isKilled": false,
"treatments": [
{
"name": "on",
"description": "The feature flag is on"
},
{
"name": "off",
"description": "The feature flag is off"
}
],
"defaultTreatment": "off",
"baselineTreatment": "off",
"trafficAllocation": 100,
"rules": [
{
"condition": {
"combiner": "AND",
"matchers": [
{
"type": "IN_LIST_STRING",
"negate": false,
"attribute": "country",
"strings": [
"US",
"CA"
]
}
]
},
"buckets": [
{
"treatment": "on",
"size": 75
},
{
"treatment": "off",
"size": 25
}
]
}
],
"defaultRule": [
{
"treatment": "off",
"size": 100
}
],
"flagSets": [
{
"id": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
],
"createdAt": "2025-06-01T12:00:00Z",
"impressions": {
"lastImpressionAt": "2025-06-15T09:30:00Z"
}
},
"governance": {
"status": "PASS",
"details": []
}
}Reallocate traffic for a Feature Flag Definition
Requires environment_id as a query parameter. Re-hashes the traffic distribution for this definition so keys may move between treatment buckets. Cannot be called while the definition is killed (400 invalidState). Unlike other mutations, reallocate does not check for pending change requests and does not require approvals.
Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.
The unique name of the feature flag 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 flag was created. System-assigned ids are not accepted.
my-new-flagPattern: ^[A-Za-z][-_A-Za-z0-9]*$Harness account identifier. Required on all endpoints.
{{accountId}}Pattern: ^[-_A-Za-z0-9]+$Environment identifier. Scopes the request to a specific environment; combined with the resource name in the path it identifies a specific environment-scoped definition (e.g., a Feature Flag Definition or a Segment Definition).
ad2eb8f0-9c3a-11ed-873c-e234abaad319Pattern: ^[-_A-Za-z0-9]+$Harness organization identifier.
defaultPattern: ^[-_A-Za-z0-9]+$Harness project identifier.
my_projectPattern: ^[-_A-Za-z0-9]+$Optional metadata supplied when killing, restoring, or reallocating a feature flag definition.
Optional comment recorded with the action.
Disabling the feature during incident mitigation.Optional title recorded with the action.
Kill billing-experience in productionOK — feature flag definition reallocated.
Feature Flag Definition entity together with the OPA governance result.
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.
POST /fme/api/v4/feature-flag-definitions/{feature-flag-name}/reallocate?account_id={{accountId}}&environment_id=ad2eb8f0-9c3a-11ed-873c-e234abaad319&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: 111
{
"comment": "Disabling the feature during incident mitigation.",
"title": "Kill billing-experience in production"
}{
"entity": {
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"featureFlag": {
"id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
"name": "my-new-flag"
},
"environment": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
"name": "Production"
},
"trafficType": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "user"
},
"isKilled": false,
"treatments": [
{
"name": "on",
"description": "The feature flag is on"
},
{
"name": "off",
"description": "The feature flag is off"
}
],
"defaultTreatment": "off",
"baselineTreatment": "off",
"trafficAllocation": 100,
"rules": [
{
"condition": {
"combiner": "AND",
"matchers": [
{
"type": "IN_LIST_STRING",
"negate": false,
"attribute": "country",
"strings": [
"US",
"CA"
]
}
]
},
"buckets": [
{
"treatment": "on",
"size": 75
},
{
"treatment": "off",
"size": 25
}
]
}
],
"defaultRule": [
{
"treatment": "off",
"size": 100
}
],
"flagSets": [
{
"id": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
],
"createdAt": "2025-06-01T12:00:00Z",
"impressions": {
"lastImpressionAt": "2025-06-15T09:30:00Z"
}
},
"governance": {
"status": "PASS",
"details": []
}
}Requires environment_id as a query parameter. Returns a single Feature Flag Definition for the specified feature flag in the specified environment.
Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.
The unique name of the feature flag 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 flag was created. System-assigned ids are not accepted.
my-new-flagPattern: ^[A-Za-z][-_A-Za-z0-9]*$Harness account identifier. Required on all endpoints.
{{accountId}}Pattern: ^[-_A-Za-z0-9]+$Environment identifier. Scopes the request to a specific environment; combined with the resource name in the path it identifies a specific environment-scoped definition (e.g., a Feature Flag Definition or a Segment Definition).
ad2eb8f0-9c3a-11ed-873c-e234abaad319Pattern: ^[-_A-Za-z0-9]+$Harness organization identifier.
defaultPattern: ^[-_A-Za-z0-9]+$Harness project identifier.
my_projectPattern: ^[-_A-Za-z0-9]+$OK — feature flag definition returned.
An environment-specific Feature Flag Definition.
System-assigned identifier for this feature flag definition.
c3d4e5f6-a7b8-9012-cdef-123456789012Whether the flag is killed in this environment. While killed, all traffic receives
defaultTreatment regardless of rules. Response-only — use the dedicated kill/restore
actions to change it.
falseTreatment name. Must start with a letter or digit; remaining characters may be letters, digits, hyphens, underscores, or periods.
onPattern: ^[a-zA-Z0-9][-_\.a-zA-Z0-9]*$Treatment name. Must start with a letter or digit; remaining characters may be letters, digits, hyphens, underscores, or periods.
onPattern: ^[a-zA-Z0-9][-_\.a-zA-Z0-9]*$Percentage of total traffic that participates in this flag's evaluation. Traffic
outside this allocation receives defaultTreatment.
100ISO-8601 timestamp when this definition was created.
2025-06-01T12:00:00ZBad 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/feature-flag-definitions/{feature-flag-name}?account_id={{accountId}}&environment_id=ad2eb8f0-9c3a-11ed-873c-e234abaad319&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",
"featureFlag": {
"id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
"name": "my-new-flag"
},
"environment": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
"name": "Production"
},
"trafficType": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "user"
},
"isKilled": false,
"treatments": [
{
"name": "on",
"description": "The feature flag is on"
},
{
"name": "off",
"description": "The feature flag is off"
}
],
"defaultTreatment": "off",
"baselineTreatment": "off",
"trafficAllocation": 100,
"rules": [
{
"condition": {
"combiner": "AND",
"matchers": [
{
"type": "IN_LIST_STRING",
"negate": false,
"attribute": "country",
"strings": [
"US",
"CA"
]
}
]
},
"buckets": [
{
"treatment": "on",
"size": 75
},
{
"treatment": "off",
"size": 25
}
]
}
],
"defaultRule": [
{
"treatment": "off",
"size": 100
}
],
"flagSets": [
{
"id": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
],
"createdAt": "2025-06-01T12:00:00Z",
"impressions": {
"lastImpressionAt": "2025-06-15T09:30:00Z"
}
}Requires environment_id as a query parameter. Creates a new Feature Flag Definition for the specified feature flag in the specified environment. A definition must not already exist for this feature flag + environment combination (409 on conflict). When the environment requires approval, returns 403. Optional flagSets associates the definition with existing flag sets by id.
Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.
The unique name of the feature flag 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 flag was created. System-assigned ids are not accepted.
my-new-flagPattern: ^[A-Za-z][-_A-Za-z0-9]*$Harness account identifier. Required on all endpoints.
{{accountId}}Pattern: ^[-_A-Za-z0-9]+$Environment identifier. Scopes the request to a specific environment; combined with the resource name in the path it identifies a specific environment-scoped definition (e.g., a Feature Flag Definition or a Segment Definition).
ad2eb8f0-9c3a-11ed-873c-e234abaad319Pattern: ^[-_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 Feature Flag Definition for the specified feature flag in the specified environment.
Treatment name. Must start with a letter or digit; remaining characters may be letters, digits, hyphens, underscores, or periods.
onPattern: ^[a-zA-Z0-9][-_\.a-zA-Z0-9]*$Treatment name. Must start with a letter or digit; remaining characters may be letters, digits, hyphens, underscores, or periods.
onPattern: ^[a-zA-Z0-9][-_\.a-zA-Z0-9]*$Percentage of traffic exposed to targeting (traffic allocation). Defaults to 100.
100Example: 100Optional audit comment recorded with the create.
Initial definition for productionOptional audit title recorded with the create.
Create production definitionCreated — the feature flag definition was successfully created.
Feature Flag Definition entity together with the OPA governance result.
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.
POST /fme/api/v4/feature-flag-definitions/{feature-flag-name}?account_id={{accountId}}&environment_id=ad2eb8f0-9c3a-11ed-873c-e234abaad319&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: 237
{
"treatments": [
{
"name": "on"
},
{
"name": "off"
}
],
"defaultTreatment": "off",
"baselineTreatment": "off",
"trafficAllocation": 100,
"rules": [],
"defaultRule": [
{
"treatment": "off",
"size": 100
}
],
"flagSets": [
{
"id": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
]
}{
"entity": {
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"featureFlag": {
"id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
"name": "my-new-flag"
},
"environment": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
"name": "Production"
},
"trafficType": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "user"
},
"isKilled": false,
"treatments": [
{
"name": "on",
"description": "The feature flag is on"
},
{
"name": "off",
"description": "The feature flag is off"
}
],
"defaultTreatment": "off",
"baselineTreatment": "off",
"trafficAllocation": 100,
"rules": [],
"defaultRule": [
{
"treatment": "off",
"size": 100
}
],
"createdAt": "2025-06-01T12:00:00Z",
"impressions": {
"lastImpressionAt": null
}
},
"governance": {
"status": "PASS",
"details": []
}
}Requires environment_id as a query parameter. Deletes a Feature Flag Definition for the specified feature flag in the specified environment. Returns the OPA governance result. Returns 409 when a pending change request already exists (pendingChangeConflict) or when the definition has active dependents (hasDependents). When the environment requires approval, returns 403.
Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.
The unique name of the feature flag 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 flag was created. System-assigned ids are not accepted.
my-new-flagPattern: ^[A-Za-z][-_A-Za-z0-9]*$Harness account identifier. Required on all endpoints.
{{accountId}}Pattern: ^[-_A-Za-z0-9]+$Environment identifier. Scopes the request to a specific environment; combined with the resource name in the path it identifies a specific environment-scoped definition (e.g., a Feature Flag Definition or a Segment Definition).
ad2eb8f0-9c3a-11ed-873c-e234abaad319Pattern: ^[-_A-Za-z0-9]+$Harness organization identifier.
defaultPattern: ^[-_A-Za-z0-9]+$Harness project identifier.
my_projectPattern: ^[-_A-Za-z0-9]+$OK — feature flag definition 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/feature-flag-definitions/{feature-flag-name}?account_id={{accountId}}&environment_id=ad2eb8f0-9c3a-11ed-873c-e234abaad319&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": []
}
}Requires environment_id as a query parameter. Partially updates a Feature Flag Definition using JSON Merge Patch semantics (RFC 7396). Field-level omit / replace / null rules are defined on UpdateFeatureFlagDefinitionRequest.
Returns 409 when a pending change request already exists for this definition. When the environment requires approval, returns 403.
Updatable fields: treatments, defaultTreatment, baselineTreatment, trafficAllocation, rules, defaultRule, flagSets, comment, title.
Harness Service Account Token (SAT) or Personal Access Token (PAT). Generate tokens in Harness under Account Settings → Access Management.
The unique name of the feature flag 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 flag was created. System-assigned ids are not accepted.
my-new-flagPattern: ^[A-Za-z][-_A-Za-z0-9]*$Harness account identifier. Required on all endpoints.
{{accountId}}Pattern: ^[-_A-Za-z0-9]+$Environment identifier. Scopes the request to a specific environment; combined with the resource name in the path it identifies a specific environment-scoped definition (e.g., a Feature Flag Definition or a Segment Definition).
ad2eb8f0-9c3a-11ed-873c-e234abaad319Pattern: ^[-_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). Omit a field to leave it unchanged. Array fields
(treatments, rules, defaultRule, flagSets) are replaced in full when present;
null for those arrays is a validation error (400). flagSets: [] is a full replace
with no associations (clears membership). Scalar fields (defaultTreatment,
baselineTreatment, trafficAllocation, comment, title) are non-clearable and
set-only — omitting the field and sending JSON null both leave the existing value
unchanged (null is treated the same as omit); there is no invent-clear, and there is no
way to clear these fields via this endpoint.
Treatment name. Must start with a letter or digit; remaining characters may be letters, digits, hyphens, underscores, or periods.
onPattern: ^[a-zA-Z0-9][-_\.a-zA-Z0-9]*$Treatment name. Must start with a letter or digit; remaining characters may be letters, digits, hyphens, underscores, or periods.
onPattern: ^[a-zA-Z0-9][-_\.a-zA-Z0-9]*$Updated traffic allocation percentage.
100Optional audit comment recorded with the update.
Ramping to 50% on-treatmentOptional audit title recorded with the update.
50% rolloutOK — feature flag definition partially updated.
Feature Flag Definition entity together with the OPA governance result.
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.
PATCH /fme/api/v4/feature-flag-definitions/{feature-flag-name}?account_id={{accountId}}&environment_id=ad2eb8f0-9c3a-11ed-873c-e234abaad319&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: 24
{
"trafficAllocation": 50
}{
"entity": {
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"featureFlag": {
"id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
"name": "my-new-flag"
},
"environment": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
"name": "Production"
},
"trafficType": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "user"
},
"isKilled": false,
"treatments": [
{
"name": "on",
"description": "The feature flag is on"
},
{
"name": "off",
"description": "The feature flag is off"
}
],
"defaultTreatment": "off",
"baselineTreatment": "off",
"trafficAllocation": 100,
"rules": [
{
"condition": {
"combiner": "AND",
"matchers": [
{
"type": "IN_LIST_STRING",
"negate": false,
"attribute": "country",
"strings": [
"US",
"CA"
]
}
]
},
"buckets": [
{
"treatment": "on",
"size": 75
},
{
"treatment": "off",
"size": 25
}
]
}
],
"defaultRule": [
{
"treatment": "off",
"size": 100
}
],
"flagSets": [
{
"id": "d4e5f6a7-b8c9-0123-def0-234567890123"
}
],
"createdAt": "2025-06-01T12:00:00Z",
"impressions": {
"lastImpressionAt": "2025-06-15T09:30:00Z"
}
},
"governance": {
"status": "PASS",
"details": []
}
}Last updated
Was this helpful?