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

Feature Flag Definitions

Manage environment-specific feature flag definitions (treatments, traffic allocation, targeting).

List Feature Flag Definitions

get
/v4/feature-flag-definitions

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.

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]+$
feature_flag_namestring · max: 100Required

The unique name of the feature flag whose definitions to list. System-assigned identifiers are not accepted.

Example: my-new-flagPattern: ^[A-Za-z][-_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
Responses
200

OK — paginated list of feature flag definitions returned.

application/json

Paginated list of active Feature Flag Definitions.

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 active feature flag definitions matching the query.

Example: 8
get/v4/feature-flag-definitions
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
}

Kill a Feature Flag Definition

post
/v4/feature-flag-definitions/{feature-flag-name}/kill

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.

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
feature-flag-namestring · max: 100Required

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.

Example: my-new-flagPattern: ^[A-Za-z][-_A-Za-z0-9]*$
Query parameters
account_idstring · max: 128Required

Harness account identifier. Required on all endpoints.

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

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

Example: ad2eb8f0-9c3a-11ed-873c-e234abaad319Pattern: ^[-_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

Optional metadata supplied when killing, restoring, or reallocating a feature flag definition.

commentstringOptional

Optional comment recorded with the action.

Example: Disabling the feature during incident mitigation.
titlestringOptional

Optional title recorded with the action.

Example: Kill billing-experience in production
Responses
200

OK — feature flag definition killed.

application/json

Feature Flag Definition entity together with the OPA governance result.

post/v4/feature-flag-definitions/{feature-flag-name}/kill
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": []
  }
}

Restore a Feature Flag Definition

post
/v4/feature-flag-definitions/{feature-flag-name}/restore

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.

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
feature-flag-namestring · max: 100Required

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.

Example: my-new-flagPattern: ^[A-Za-z][-_A-Za-z0-9]*$
Query parameters
account_idstring · max: 128Required

Harness account identifier. Required on all endpoints.

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

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

Example: ad2eb8f0-9c3a-11ed-873c-e234abaad319Pattern: ^[-_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

Optional metadata supplied when killing, restoring, or reallocating a feature flag definition.

commentstringOptional

Optional comment recorded with the action.

Example: Disabling the feature during incident mitigation.
titlestringOptional

Optional title recorded with the action.

Example: Kill billing-experience in production
Responses
200

OK — feature flag definition restored.

application/json

Feature Flag Definition entity together with the OPA governance result.

post/v4/feature-flag-definitions/{feature-flag-name}/restore
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

post
/v4/feature-flag-definitions/{feature-flag-name}/reallocate

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.

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
feature-flag-namestring · max: 100Required

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.

Example: my-new-flagPattern: ^[A-Za-z][-_A-Za-z0-9]*$
Query parameters
account_idstring · max: 128Required

Harness account identifier. Required on all endpoints.

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

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

Example: ad2eb8f0-9c3a-11ed-873c-e234abaad319Pattern: ^[-_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

Optional metadata supplied when killing, restoring, or reallocating a feature flag definition.

commentstringOptional

Optional comment recorded with the action.

Example: Disabling the feature during incident mitigation.
titlestringOptional

Optional title recorded with the action.

Example: Kill billing-experience in production
Responses
200

OK — feature flag definition reallocated.

application/json

Feature Flag Definition entity together with the OPA governance result.

post/v4/feature-flag-definitions/{feature-flag-name}/reallocate
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": []
  }
}

Get a Feature Flag Definition

get
/v4/feature-flag-definitions/{feature-flag-name}

Requires environment_id as a query parameter. Returns a single Feature Flag Definition for the specified feature flag in the specified environment.

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
feature-flag-namestring · max: 100Required

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.

Example: my-new-flagPattern: ^[A-Za-z][-_A-Za-z0-9]*$
Query parameters
account_idstring · max: 128Required

Harness account identifier. Required on all endpoints.

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

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

Example: ad2eb8f0-9c3a-11ed-873c-e234abaad319Pattern: ^[-_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 — feature flag definition returned.

application/json

An environment-specific Feature Flag Definition.

idstring · uuidRequired

System-assigned identifier for this feature flag definition.

Example: c3d4e5f6-a7b8-9012-cdef-123456789012
isKilledbooleanRead-onlyRequired

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

Example: false
defaultTreatmentstringRequired

Treatment name. Must start with a letter or digit; remaining characters may be letters, digits, hyphens, underscores, or periods.

Example: onPattern: ^[a-zA-Z0-9][-_\.a-zA-Z0-9]*$
baselineTreatmentstringRequired

Treatment name. Must start with a letter or digit; remaining characters may be letters, digits, hyphens, underscores, or periods.

Example: onPattern: ^[a-zA-Z0-9][-_\.a-zA-Z0-9]*$
trafficAllocationinteger · int32 · max: 100Required

Percentage of total traffic that participates in this flag's evaluation. Traffic outside this allocation receives defaultTreatment.

Example: 100
createdAtstring · date-timeRequired

ISO-8601 timestamp when this definition was created.

Example: 2025-06-01T12:00:00Z
get/v4/feature-flag-definitions/{feature-flag-name}
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"
  }
}

Create a Feature Flag Definition

post
/v4/feature-flag-definitions/{feature-flag-name}

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.

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
feature-flag-namestring · max: 100Required

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.

Example: my-new-flagPattern: ^[A-Za-z][-_A-Za-z0-9]*$
Query parameters
account_idstring · max: 128Required

Harness account identifier. Required on all endpoints.

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

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

Example: ad2eb8f0-9c3a-11ed-873c-e234abaad319Pattern: ^[-_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 Feature Flag Definition for the specified feature flag in the specified environment.

defaultTreatmentstringRequired

Treatment name. Must start with a letter or digit; remaining characters may be letters, digits, hyphens, underscores, or periods.

Example: onPattern: ^[a-zA-Z0-9][-_\.a-zA-Z0-9]*$
baselineTreatmentstringOptional

Treatment name. Must start with a letter or digit; remaining characters may be letters, digits, hyphens, underscores, or periods.

Example: onPattern: ^[a-zA-Z0-9][-_\.a-zA-Z0-9]*$
trafficAllocationinteger · int32 · max: 100Optional

Percentage of traffic exposed to targeting (traffic allocation). Defaults to 100.

Default: 100Example: 100
commentstringOptional

Optional audit comment recorded with the create.

Example: Initial definition for production
titlestringOptional

Optional audit title recorded with the create.

Example: Create production definition
Responses
201

Created — the feature flag definition was successfully created.

application/json

Feature Flag Definition entity together with the OPA governance result.

post/v4/feature-flag-definitions/{feature-flag-name}
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": []
  }
}

Delete a Feature Flag Definition

delete
/v4/feature-flag-definitions/{feature-flag-name}

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.

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
feature-flag-namestring · max: 100Required

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.

Example: my-new-flagPattern: ^[A-Za-z][-_A-Za-z0-9]*$
Query parameters
account_idstring · max: 128Required

Harness account identifier. Required on all endpoints.

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

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

Example: ad2eb8f0-9c3a-11ed-873c-e234abaad319Pattern: ^[-_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 — feature flag definition 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/feature-flag-definitions/{feature-flag-name}
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": []
  }
}

Update a Feature Flag Definition (partial)

patch
/v4/feature-flag-definitions/{feature-flag-name}

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.

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
feature-flag-namestring · max: 100Required

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.

Example: my-new-flagPattern: ^[A-Za-z][-_A-Za-z0-9]*$
Query parameters
account_idstring · max: 128Required

Harness account identifier. Required on all endpoints.

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

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

Example: ad2eb8f0-9c3a-11ed-873c-e234abaad319Pattern: ^[-_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). 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.

defaultTreatmentstringOptional

Treatment name. Must start with a letter or digit; remaining characters may be letters, digits, hyphens, underscores, or periods.

Example: onPattern: ^[a-zA-Z0-9][-_\.a-zA-Z0-9]*$
baselineTreatmentstringOptional

Treatment name. Must start with a letter or digit; remaining characters may be letters, digits, hyphens, underscores, or periods.

Example: onPattern: ^[a-zA-Z0-9][-_\.a-zA-Z0-9]*$
trafficAllocationinteger · int32 · max: 100Optional

Updated traffic allocation percentage.

Example: 100
commentstringOptional

Optional audit comment recorded with the update.

Example: Ramping to 50% on-treatment
titlestringOptional

Optional audit title recorded with the update.

Example: 50% rollout
Responses
200

OK — feature flag definition partially updated.

application/json

Feature Flag Definition entity together with the OPA governance result.

patch/v4/feature-flag-definitions/{feature-flag-name}
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?