Feature Flags
Manage workspace-scoped feature flag metadata and lifecycle (create, list, get, update, delete, archive, unarchive).
Returns a paginated list of Feature Flags in the specified project workspace. Defaults to active flags (status defaults to [ACTIVE]). Results can be filtered by status, name, tags, rollout statuses, or feature flag identifiers and are sorted by name in ascending order.
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: 0Filter by flag name (partial, case-insensitive match).
checkoutFilter to flags that have any of the specified tags (by tag name).
["backend","checkout"]Filter by one or more system-assigned rollout status identifiers.
["ad2eb8f0-9c3a-11ed-873c-e234abaad319"]Filter to specific flag IDs. Useful for bulk lookups.
["a1b2c3d4-e5f6-7890-abcd-ef1234567890","b2c3d4e5-f6a7-8901-bcde-f12345678901"]Sort order. Only name:asc is supported. Defaults to name:asc.
name:ascExample: name:ascPossible values: OK — paginated list of feature flags returned.
Paginated list of Feature Flags matching the query.
The page size used for this response.
100The number of items skipped before the first result.
0Total number of feature flags 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/feature-flags?account_id={{accountId}}&organization_identifier=default&project_identifier=my_project HTTP/1.1
Host: app.harness.io
x-api-key: YOUR_API_KEY
Accept: */*
{
"data": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "my-new-flag",
"description": "Controls the new checkout experience",
"trafficType": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
"name": "user"
},
"createdAt": "2025-06-01T12:00:00Z",
"status": "ACTIVE",
"rolloutStatus": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
"name": "Pre-Production"
},
"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"
}
]
}
],
"limit": 100,
"offset": 0,
"totalCount": 42
}Creates a new Feature Flag in the specified project workspace. The feature flag name must be unique within 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]+$Request body for creating a new Feature Flag.
Unique feature flag name within the project. Immutable after creation.
my-new-flagPattern: ^[A-Za-z][-_A-Za-z0-9]*$Human-readable description of this feature flag.
Controls the new checkout experienceTraffic type used to bucket users, identified by its name (for example user or
account). Immutable after creation.
userCreated — the feature flag was successfully created.
Mutation response (create, update, archive, unarchive): 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/feature-flags?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: 179
{
"name": "my-new-flag",
"description": "Controls the new checkout experience",
"trafficType": "user",
"tags": [
{
"name": "backend"
}
],
"owners": [
{
"type": "USER",
"email": "alice@example.com"
}
]
}{
"entity": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "my-new-flag",
"description": "Controls the new checkout experience",
"trafficType": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
"name": "user"
},
"createdAt": "2025-06-01T12:00:00Z",
"status": "ACTIVE",
"rolloutStatus": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
"name": "Pre-Production"
},
"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"
}
]
},
"governance": {
"status": "PASS",
"details": []
}
}Returns a single Feature Flag by name. Unlike list, this endpoint returns the flag regardless of lifecycle status (ACTIVE or ARCHIVED).
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]+$Harness organization identifier.
defaultPattern: ^[-_A-Za-z0-9]+$Harness project identifier.
my_projectPattern: ^[-_A-Za-z0-9]+$OK — feature flag returned.
A workspace-scoped Feature Flag entity.
Unique system-assigned identifier for the feature flag.
a1b2c3d4-e5f6-7890-abcd-ef1234567890Unique feature flag name within the project. Immutable after creation — use this as the path parameter in subsequent requests.
my-new-flagHuman-readable description of this feature flag.
Controls the new checkout experienceISO-8601 timestamp when the feature flag was created.
2025-06-01T12:00:00ZLifecycle status of the feature flag.
ACTIVE— flag is live.ARCHIVED— flag is no longer active and is read-only.
ACTIVEPossible 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/feature-flags/{feature-flag-name}?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": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "my-new-flag",
"description": "Controls the new checkout experience",
"trafficType": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
"name": "user"
},
"createdAt": "2025-06-01T12:00:00Z",
"status": "ACTIVE",
"rolloutStatus": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
"name": "Pre-Production"
},
"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"
}
]
}Deletes a Feature Flag. Returns the OPA governance result for the operation. Deleting a flag that has active dependents returns 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 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]+$Harness organization identifier.
defaultPattern: ^[-_A-Za-z0-9]+$Harness project identifier.
my_projectPattern: ^[-_A-Za-z0-9]+$OK — feature flag 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-flags/{feature-flag-name}?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 Feature Flag using JSON Merge Patch semantics (RFC 7396). Only fields present in the request body are modified; omitted fields are left unchanged. JSON null (or [] for arrays) clears description, tags, and owners. rolloutStatus cannot be cleared: omit the field to leave it unchanged; JSON null returns 400.
Only ACTIVE feature flags can be updated. Patching a non-active flag returns 400 (invalidState). Changing rollout status while an open change request exists returns 409 (pendingChangeConflict).
Updatable fields: description, tags, owners, rolloutStatus.
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]+$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 Feature Flag. All fields are optional. Omit a
field to leave it unchanged. JSON null (or [] for arrays) clears description, tags,
and owners. rolloutStatus cannot be cleared: omit to keep; JSON null returns 400.
Updated human-readable description.
Updated feature flag descriptionOK — feature flag updated.
Mutation response (create, update, archive, unarchive): 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).
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-flags/{feature-flag-name}?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: 135
{
"description": "Updated feature flag description",
"tags": [
{
"name": "backend"
}
],
"owners": [
{
"type": "GROUP",
"identifier": "platform-team"
}
]
}{
"entity": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "my-new-flag",
"description": "Controls the new checkout experience",
"trafficType": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
"name": "user"
},
"createdAt": "2025-06-01T12:00:00Z",
"status": "ACTIVE",
"rolloutStatus": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
"name": "Pre-Production"
},
"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"
}
]
},
"governance": {
"status": "PASS",
"details": []
}
}Archives a Feature Flag and cascades the archived state to all definitions across all environments. Once archived, definitions cannot be modified until the flag is unarchived. Archiving a flag that is already ARCHIVED returns 400 (invalidState). Archiving a flag that has active dependents returns 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 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]+$Harness organization identifier.
defaultPattern: ^[-_A-Za-z0-9]+$Harness project identifier.
my_projectPattern: ^[-_A-Za-z0-9]+$Optional metadata supplied when archiving or unarchiving a feature flag.
Optional comment recorded with the action.
Flag no longer needed after Q3 cleanupOK — feature flag archived.
Mutation response (create, update, archive, unarchive): 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).
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-flags/{feature-flag-name}/archive?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: 52
{
"comment": "Flag no longer needed after Q3 cleanup"
}{
"entity": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "my-new-flag",
"description": "Controls the new checkout experience",
"trafficType": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
"name": "user"
},
"createdAt": "2025-06-01T12:00:00Z",
"status": "ACTIVE",
"rolloutStatus": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
"name": "Pre-Production"
},
"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"
}
]
},
"governance": {
"status": "PASS",
"details": []
}
}Restores a previously archived Feature Flag to active state so its definitions can be modified again. Unarchiving a flag that is already ACTIVE returns 400 (invalidState).
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]+$Harness organization identifier.
defaultPattern: ^[-_A-Za-z0-9]+$Harness project identifier.
my_projectPattern: ^[-_A-Za-z0-9]+$Optional metadata supplied when archiving or unarchiving a feature flag.
Optional comment recorded with the action.
Flag no longer needed after Q3 cleanupOK — feature flag unarchived.
Mutation response (create, update, archive, unarchive): 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).
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-flags/{feature-flag-name}/unarchive?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: 52
{
"comment": "Flag no longer needed after Q3 cleanup"
}{
"entity": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "my-new-flag",
"description": "Controls the new checkout experience",
"trafficType": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
"name": "user"
},
"createdAt": "2025-06-01T12:00:00Z",
"status": "ACTIVE",
"rolloutStatus": {
"id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
"name": "Pre-Production"
},
"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"
}
]
},
"governance": {
"status": "PASS",
"details": []
}
}Last updated
Was this helpful?