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

Feature Flags

Manage workspace-scoped feature flag metadata and lifecycle (create, list, get, update, delete, archive, unarchive).

List Feature Flags

get
/v4/feature-flags

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.

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
namestringOptional

Filter by flag name (partial, case-insensitive match).

Example: checkout
tagsstring[]Optional

Filter to flags that have any of the specified tags (by tag name).

Example: ["backend","checkout"]
rollout_statusesstring · uuid[]Optional

Filter by one or more system-assigned rollout status identifiers.

Example: ["ad2eb8f0-9c3a-11ed-873c-e234abaad319"]
idsstring · uuid[]Optional

Filter to specific flag IDs. Useful for bulk lookups.

Example: ["a1b2c3d4-e5f6-7890-abcd-ef1234567890","b2c3d4e5-f6a7-8901-bcde-f12345678901"]
sortstring · enumOptional

Sort order. Only name:asc is supported. Defaults to name:asc.

Default: name:ascExample: name:ascPossible values:
Responses
200

OK — paginated list of feature flags returned.

application/json

Paginated list of Feature Flags 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 feature flags matching the query.

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

Create a Feature Flag

post
/v4/feature-flags

Creates a new Feature Flag in the specified project workspace. The feature flag name must be unique within 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]+$
Body

Request body for creating a new Feature Flag.

namestring · max: 100Required

Unique feature flag name within the project. Immutable after creation.

Example: my-new-flagPattern: ^[A-Za-z][-_A-Za-z0-9]*$
descriptionstringOptional

Human-readable description of this feature flag.

Example: Controls the new checkout experience
trafficTypestringRequired

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

Example: user
Responses
201

Created — the feature flag was successfully created.

application/json

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

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

Get a Feature Flag

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

Returns a single Feature Flag by name. Unlike list, this endpoint returns the flag regardless of lifecycle status (ACTIVE or ARCHIVED).

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]+$
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 returned.

application/json

A workspace-scoped Feature Flag entity.

idstring · uuidRequired

Unique system-assigned identifier for the feature flag.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
namestringRequired

Unique feature flag name within the project. Immutable after creation — use this as the path parameter in subsequent requests.

Example: my-new-flag
descriptionstring · nullableOptional

Human-readable description of this feature flag.

Example: Controls the new checkout experience
createdAtstring · date-timeRequired

ISO-8601 timestamp when the feature flag was created.

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

Lifecycle status of the feature flag.

  • ACTIVE — flag is live.
  • ARCHIVED — flag is no longer active and is read-only.
Example: ACTIVEPossible values:
get/v4/feature-flags/{feature-flag-name}
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"
    }
  ]
}

Delete a Feature Flag

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

Deletes a Feature Flag. Returns the OPA governance result for the operation. Deleting a flag that has active dependents returns 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
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]+$
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 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-flags/{feature-flag-name}
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": []
  }
}

Update a Feature Flag (partial)

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

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.

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]+$
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 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.

descriptionstring · nullableOptional

Updated human-readable description.

Example: Updated feature flag description
Responses
200

OK — feature flag updated.

application/json

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

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

Archive a Feature Flag

post
/v4/feature-flags/{feature-flag-name}/archive

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

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]+$
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 archiving or unarchiving a feature flag.

commentstringOptional

Optional comment recorded with the action.

Example: Flag no longer needed after Q3 cleanup
Responses
200

OK — feature flag archived.

application/json

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

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

Unarchive a Feature Flag

post
/v4/feature-flags/{feature-flag-name}/unarchive

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

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]+$
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 archiving or unarchiving a feature flag.

commentstringOptional

Optional comment recorded with the action.

Example: Flag no longer needed after Q3 cleanup
Responses
200

OK — feature flag unarchived.

application/json

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

post/v4/feature-flags/{feature-flag-name}/unarchive
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?