{
  "openapi": "3.0.3",
  "info": {
    "title": "Harness Feature Management & Experimentation API",
    "version": "4.0.0",
    "description": "Public REST API for managing Harness Feature Management & Experimentation (FME) resources.\n\n## Authentication\n\nAll endpoints require a Harness Service Account Token (SAT) or Personal Access Token (PAT) supplied in the `x-api-key` request header."
  },
  "servers": [
    {
      "url": "https://app.harness.io/fme/api",
      "description": "Harness SaaS (production)"
    },
    {
      "url": "https://app3.harness.io/fme/api",
      "description": "Harness SaaS (US-3)"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Feature Flags",
      "description": "Manage workspace-scoped feature flag metadata and lifecycle (create, list, get, update, delete, archive, unarchive)."
    },
    {
      "name": "Feature Flag Definitions",
      "description": "Manage environment-specific feature flag definitions (treatments, traffic allocation, targeting)."
    },
    {
      "name": "Segments",
      "description": "Manage workspace-scoped STANDARD, LARGE, and RULE_BASED segment metadata and lifecycle."
    },
    {
      "name": "Segment Definitions",
      "description": "Manage environment-specific standard segment instances (description, keys, segment and\nenvironment references, soft-delete).\n"
    },
    {
      "name": "Environments",
      "description": "Manage workspace-scoped deployment environments (name, production flag, lifecycle state)."
    },
    {
      "name": "Traffic Types",
      "description": "List workspace-scoped traffic types."
    },
    {
      "name": "Event Types",
      "description": "List and get project-scoped event types."
    },
    {
      "name": "Experiments",
      "description": "Manage workspace-scoped Experiments."
    },
    {
      "name": "Metrics",
      "description": "Manage project-scoped metric definitions (create, list, get, update, delete)."
    }
  ],
  "paths": {
    "/v4/feature-flags": {
      "post": {
        "tags": [
          "Feature Flags"
        ],
        "operationId": "createFeatureFlag",
        "summary": "Create a Feature Flag",
        "description": "Creates a new Feature Flag in the specified project workspace. The feature flag name must be\nunique within the project.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateFeatureFlagRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created — the feature flag was successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureFlagResponse"
                },
                "example": {
                  "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": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "get": {
        "tags": [
          "Feature Flags"
        ],
        "operationId": "listFeatureFlags",
        "summary": "List Feature Flags",
        "description": "Returns a paginated list of Feature Flags in the specified project workspace.\nDefaults to active flags (`status` defaults to `[ACTIVE]`). Results can be filtered by\nstatus, name, tags, rollout statuses, or feature flag identifiers and are sorted by name\nin ascending order.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          },
          {
            "$ref": "#/components/parameters/PaginationLimitParam"
          },
          {
            "$ref": "#/components/parameters/PaginationOffsetParam"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by lifecycle status. Defaults to `[ACTIVE]`. Explicit values replace the default.\n",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "ACTIVE",
                  "ARCHIVED"
                ]
              },
              "default": [
                "ACTIVE"
              ]
            },
            "style": "form",
            "explode": true,
            "example": [
              "ACTIVE"
            ]
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Filter by flag name (partial, case-insensitive match).",
            "schema": {
              "type": "string",
              "example": "checkout"
            }
          },
          {
            "name": "tags",
            "in": "query",
            "required": false,
            "description": "Filter to flags that have any of the specified tags (by tag name).",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true,
            "example": [
              "backend",
              "checkout"
            ]
          },
          {
            "name": "rollout_statuses",
            "in": "query",
            "required": false,
            "description": "Filter by one or more system-assigned rollout status identifiers.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid"
              }
            },
            "style": "form",
            "explode": true,
            "example": [
              "ad2eb8f0-9c3a-11ed-873c-e234abaad319"
            ]
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "description": "Filter to specific flag IDs. Useful for bulk lookups.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid"
              }
            },
            "style": "form",
            "explode": true,
            "example": [
              "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
              "b2c3d4e5-f6a7-8901-bcde-f12345678901"
            ]
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort order. Only `name:asc` is supported. Defaults to `name:asc`.",
            "schema": {
              "type": "string",
              "enum": [
                "name:asc"
              ],
              "default": "name:asc"
            },
            "example": "name:asc"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — paginated list of feature flags returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureFlagListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/feature-flags/{feature-flag-name}": {
      "get": {
        "tags": [
          "Feature Flags"
        ],
        "operationId": "getFeatureFlag",
        "summary": "Get a Feature Flag",
        "description": "Returns a single Feature Flag by name. Unlike list, this endpoint returns the flag regardless\nof lifecycle status (`ACTIVE` or `ARCHIVED`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/FeatureFlagName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — feature flag returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureFlag"
                },
                "example": {
                  "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"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "patch": {
        "tags": [
          "Feature Flags"
        ],
        "operationId": "updateFeatureFlag",
        "summary": "Update a Feature Flag (partial)",
        "description": "Partially updates a Feature Flag using JSON Merge Patch semantics (RFC 7396). Only fields\npresent in the request body are modified; omitted fields are left unchanged. JSON `null` (or\n`[]` for arrays) clears `description`, `tags`, and `owners`. `rolloutStatus` cannot be\ncleared: omit the field to leave it unchanged; JSON `null` returns `400`.\n\nOnly `ACTIVE` feature flags can be updated. Patching a non-active flag returns `400`\n(`invalidState`). Changing rollout status while an open change request exists returns `409`\n(`pendingChangeConflict`).\n\n**Updatable fields:** `description`, `tags`, `owners`, `rolloutStatus`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/FeatureFlagName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/merge-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateFeatureFlagRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — feature flag updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureFlagResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "delete": {
        "tags": [
          "Feature Flags"
        ],
        "operationId": "deleteFeatureFlag",
        "summary": "Delete a Feature Flag",
        "description": "Deletes a Feature Flag. Returns the OPA governance result for the operation. Deleting a\nflag that has active dependents returns `409` (`hasDependents`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/FeatureFlagName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — feature flag deleted. Returns the governance result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteResponse"
                },
                "example": {
                  "governance": {
                    "status": "PASS",
                    "details": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/feature-flags/{feature-flag-name}/archive": {
      "post": {
        "tags": [
          "Feature Flags"
        ],
        "operationId": "archiveFeatureFlag",
        "summary": "Archive a Feature Flag",
        "description": "Archives a Feature Flag and cascades the archived state to all definitions across all\nenvironments. Once archived, definitions cannot be modified until the flag is unarchived.\nArchiving a flag that is already `ARCHIVED` returns `400` (`invalidState`). Archiving a\nflag that has active dependents returns `409` (`hasDependents`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/FeatureFlagName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ArchiveUnarchiveFeatureFlagRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — feature flag archived.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureFlagResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/feature-flags/{feature-flag-name}/unarchive": {
      "post": {
        "tags": [
          "Feature Flags"
        ],
        "operationId": "unarchiveFeatureFlag",
        "summary": "Unarchive a Feature Flag",
        "description": "Restores a previously archived Feature Flag to active state so its definitions can be\nmodified again. Unarchiving a flag that is already `ACTIVE` returns `400` (`invalidState`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/FeatureFlagName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ArchiveUnarchiveFeatureFlagRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — feature flag unarchived.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureFlagResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/feature-flag-definitions": {
      "get": {
        "tags": [
          "Feature Flag Definitions"
        ],
        "operationId": "listFeatureFlagDefinitions",
        "summary": "List Feature Flag Definitions",
        "description": "Returns a paginated list of active Feature Flag Definitions across all environments for the\nFeature Flag specified by `feature_flag_name`. Returns `404` if no Feature Flag with that\nname exists in the project.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          },
          {
            "name": "feature_flag_name",
            "in": "query",
            "required": true,
            "description": "The unique name of the feature flag whose definitions to list. System-assigned\nidentifiers are not accepted.\n",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z][-_A-Za-z0-9]*$",
              "maxLength": 100,
              "example": "my-new-flag"
            }
          },
          {
            "$ref": "#/components/parameters/PaginationLimitParam"
          },
          {
            "$ref": "#/components/parameters/PaginationOffsetParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — paginated list of feature flag definitions returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureFlagDefinitionListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/feature-flag-definitions/{feature-flag-name}/kill": {
      "post": {
        "tags": [
          "Feature Flag Definitions"
        ],
        "operationId": "killFeatureFlagDefinition",
        "summary": "Kill a Feature Flag Definition",
        "description": "Requires `environment_id` as a query parameter. Kills the Feature Flag Definition for the\nspecified feature flag in the specified environment. A killed definition serves the default\ntreatment. Any pending change request for this definition is auto-rejected so the kill can\nproceed.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/FeatureFlagName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/EnvironmentId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FeatureFlagDefinitionActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — feature flag definition killed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureFlagDefinitionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/feature-flag-definitions/{feature-flag-name}/restore": {
      "post": {
        "tags": [
          "Feature Flag Definitions"
        ],
        "operationId": "restoreFeatureFlagDefinition",
        "summary": "Restore a Feature Flag Definition",
        "description": "Requires `environment_id` as a query parameter. Restores the Feature Flag Definition for\nthe specified feature flag in the specified environment after it was killed. Returns `409`\nwhen a pending change request already exists for this definition, `400` (`invalidState`)\nwhen the definition is not currently killed, and `403` when the environment requires\napproval.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/FeatureFlagName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/EnvironmentId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FeatureFlagDefinitionActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — feature flag definition restored.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureFlagDefinitionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/feature-flag-definitions/{feature-flag-name}/reallocate": {
      "post": {
        "tags": [
          "Feature Flag Definitions"
        ],
        "operationId": "reallocateFeatureFlagDefinition",
        "summary": "Reallocate traffic for a Feature Flag Definition",
        "description": "Requires `environment_id` as a query parameter. Re-hashes the traffic distribution for this\ndefinition so keys may move between treatment buckets. Cannot be called while the\ndefinition is killed (`400` `invalidState`). Unlike other mutations, reallocate does not\ncheck for pending change requests and does not require approvals.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/FeatureFlagName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/EnvironmentId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FeatureFlagDefinitionActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — feature flag definition reallocated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureFlagDefinitionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/feature-flag-definitions/{feature-flag-name}": {
      "post": {
        "tags": [
          "Feature Flag Definitions"
        ],
        "operationId": "createFeatureFlagDefinition",
        "summary": "Create a Feature Flag Definition",
        "description": "Requires `environment_id` as a query parameter. Creates a new Feature Flag Definition for\nthe specified feature flag in the specified environment. A definition must not already exist\nfor this feature flag + environment combination (`409` on conflict). When the environment\nrequires approval, returns `403`. Optional `flagSets` associates the definition with\nexisting flag sets by id.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/FeatureFlagName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/EnvironmentId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateFeatureFlagDefinitionRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created — the feature flag definition was successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureFlagDefinitionResponse"
                },
                "example": {
                  "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": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "get": {
        "tags": [
          "Feature Flag Definitions"
        ],
        "operationId": "getFeatureFlagDefinition",
        "summary": "Get a Feature Flag Definition",
        "description": "Requires `environment_id` as a query parameter. Returns a single Feature Flag Definition\nfor the specified feature flag in the specified environment.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/FeatureFlagName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/EnvironmentId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — feature flag definition returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureFlagDefinition"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "patch": {
        "tags": [
          "Feature Flag Definitions"
        ],
        "operationId": "updateFeatureFlagDefinition",
        "summary": "Update a Feature Flag Definition (partial)",
        "description": "Requires `environment_id` as a query parameter. Partially updates a Feature Flag Definition\nusing JSON Merge Patch semantics (RFC 7396). Field-level omit / replace / null rules are\ndefined on `UpdateFeatureFlagDefinitionRequest`.\n\nReturns `409` when a pending change request already exists for this definition. When the\nenvironment requires approval, returns `403`.\n\n**Updatable fields:** `treatments`, `defaultTreatment`, `baselineTreatment`,\n`trafficAllocation`, `rules`, `defaultRule`, `flagSets`, `comment`, `title`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/FeatureFlagName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/EnvironmentId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/merge-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateFeatureFlagDefinitionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — feature flag definition partially updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeatureFlagDefinitionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "delete": {
        "tags": [
          "Feature Flag Definitions"
        ],
        "operationId": "deleteFeatureFlagDefinition",
        "summary": "Delete a Feature Flag Definition",
        "description": "Requires `environment_id` as a query parameter. Deletes a Feature Flag Definition for the\nspecified feature flag in the specified environment. Returns the OPA governance result.\nReturns `409` when a pending change request already exists (`pendingChangeConflict`) or\nwhen the definition has active dependents (`hasDependents`). When the environment requires\napproval, returns `403`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/FeatureFlagName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/EnvironmentId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — feature flag definition deleted. Returns the governance result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteResponse"
                },
                "example": {
                  "governance": {
                    "status": "PASS",
                    "details": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/segments": {
      "post": {
        "tags": [
          "Segments"
        ],
        "operationId": "createSegment",
        "summary": "Create a Segment",
        "description": "Creates a Segment. JSON `segmentType` is required. Creating `RULE_BASED` when the account\ncannot use rule-based segments returns `400`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSegmentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created — the segment was successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentResponse"
                },
                "example": {
                  "entity": {
                    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
                    "name": "power-users",
                    "description": "Users with elevated privileges",
                    "trafficType": {
                      "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
                      "name": "user"
                    },
                    "createdAt": "2025-06-01T12:00:00Z",
                    "status": "ACTIVE",
                    "tags": [
                      {
                        "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad322",
                        "name": "backend"
                      }
                    ],
                    "owners": [
                      {
                        "id": "xM5qi75eQYmdgJYfwNoHEQ",
                        "type": "USER",
                        "name": "Alice Example",
                        "email": "alice@example.com"
                      },
                      {
                        "id": "VP5X_K9mTqR2nLw8sYcHdA",
                        "type": "GROUP",
                        "name": "platform-team"
                      }
                    ],
                    "segmentType": "STANDARD"
                  },
                  "governance": {
                    "status": "PASS",
                    "details": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "get": {
        "tags": [
          "Segments"
        ],
        "operationId": "listSegments",
        "summary": "List Segments",
        "description": "Returns a paginated list of Segments of one kind. `segment_type` is required (`400` if\nomitted). Defaults to active segments (`status` defaults to `[ACTIVE]`). More than one\n`status` returns `400`. Sorted by name ascending.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          },
          {
            "$ref": "#/components/parameters/PaginationLimitParam"
          },
          {
            "$ref": "#/components/parameters/PaginationOffsetParam"
          },
          {
            "$ref": "#/components/parameters/SegmentType"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by lifecycle status. Defaults to `[ACTIVE]`. A single value only; more than one\nreturns `400`.\n",
            "schema": {
              "type": "array",
              "maxItems": 1,
              "items": {
                "type": "string",
                "enum": [
                  "ACTIVE",
                  "ARCHIVED"
                ]
              },
              "default": [
                "ACTIVE"
              ]
            },
            "style": "form",
            "explode": true,
            "example": [
              "ACTIVE"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "OK — paginated list of segments returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentListResponse"
                },
                "example": {
                  "data": [
                    {
                      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
                      "name": "power-users",
                      "description": "Users with elevated privileges",
                      "trafficType": {
                        "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
                        "name": "user"
                      },
                      "createdAt": "2025-06-01T12:00:00Z",
                      "status": "ACTIVE",
                      "tags": [
                        {
                          "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad322",
                          "name": "backend"
                        }
                      ],
                      "owners": [
                        {
                          "id": "xM5qi75eQYmdgJYfwNoHEQ",
                          "type": "USER",
                          "name": "Alice Example",
                          "email": "alice@example.com"
                        },
                        {
                          "id": "VP5X_K9mTqR2nLw8sYcHdA",
                          "type": "GROUP",
                          "name": "platform-team"
                        }
                      ],
                      "segmentType": "STANDARD"
                    }
                  ],
                  "limit": 100,
                  "offset": 0,
                  "totalCount": 42
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/segments/{segment-name}": {
      "get": {
        "tags": [
          "Segments"
        ],
        "operationId": "getSegment",
        "summary": "Get a Segment",
        "description": "Active segment by name and `segment_type`. Omitting `segment_type` returns `400`.\nARCHIVED names return `404`; use LIST with `status=ARCHIVED` to discover them.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/SegmentName"
          },
          {
            "$ref": "#/components/parameters/SegmentType"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — segment returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Segment"
                },
                "example": {
                  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
                  "name": "power-users",
                  "description": "Users with elevated privileges",
                  "trafficType": {
                    "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
                    "name": "user"
                  },
                  "createdAt": "2025-06-01T12:00:00Z",
                  "status": "ACTIVE",
                  "tags": [
                    {
                      "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad322",
                      "name": "backend"
                    }
                  ],
                  "owners": [
                    {
                      "id": "xM5qi75eQYmdgJYfwNoHEQ",
                      "type": "USER",
                      "name": "Alice Example",
                      "email": "alice@example.com"
                    },
                    {
                      "id": "VP5X_K9mTqR2nLw8sYcHdA",
                      "type": "GROUP",
                      "name": "platform-team"
                    }
                  ],
                  "segmentType": "STANDARD"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "patch": {
        "tags": [
          "Segments"
        ],
        "operationId": "updateSegment",
        "summary": "Update a Segment (partial)",
        "description": "Partially updates a Segment (RFC 7396). Omit = keep; JSON `null` clears `description`;\n`null` or `[]` clears `tags`/`owners`. `segment_type` is required (`400` if omitted).\nAlready-archived segments return `404`. `segmentType` is not patchable.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/SegmentName"
          },
          {
            "$ref": "#/components/parameters/SegmentType"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/merge-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSegmentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — segment updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "delete": {
        "tags": [
          "Segments"
        ],
        "operationId": "deleteSegment",
        "summary": "Delete a Segment",
        "description": "Archives a Segment of the given `segment_type` (`400` if omitted). Returns the OPA\ngovernance result for the operation. Already archived or missing names return `404`.\nActive dependents return `409` (`hasDependents`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/SegmentName"
          },
          {
            "$ref": "#/components/parameters/SegmentType"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — segment deleted. Returns the governance result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteResponse"
                },
                "example": {
                  "governance": {
                    "status": "PASS",
                    "details": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/segment-definitions": {
      "get": {
        "tags": [
          "Segment Definitions"
        ],
        "operationId": "listSegmentDefinitions",
        "summary": "List Segment Definitions",
        "description": "Returns a paginated list of Segment Definitions in the Environment specified by\n`environment_id`. Defaults to active definitions (`status` defaults to `[ACTIVE]`).\nMore than one `status` returns `400`. Returns `404` if `environment_id` does not identify\nan active Environment in the project.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          },
          {
            "$ref": "#/components/parameters/EnvironmentId"
          },
          {
            "$ref": "#/components/parameters/PaginationLimitParam"
          },
          {
            "$ref": "#/components/parameters/PaginationOffsetParam"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by lifecycle status. Defaults to `[ACTIVE]`. A single value only; more than one\n`status` returns `400`.\n",
            "schema": {
              "type": "array",
              "maxItems": 1,
              "items": {
                "type": "string",
                "enum": [
                  "ACTIVE",
                  "ARCHIVED"
                ]
              },
              "default": [
                "ACTIVE"
              ]
            },
            "style": "form",
            "explode": true,
            "example": [
              "ACTIVE"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "OK — paginated list of segment definitions returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentDefinitionListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/segment-definitions/{segment-name}": {
      "post": {
        "tags": [
          "Segment Definitions"
        ],
        "operationId": "createSegmentDefinition",
        "summary": "Create a Segment Definition",
        "description": "Requires `environment_id` as a query parameter. Creates a new Segment Definition for the\nspecified segment in the specified environment. A definition must not already exist for\nthis segment + environment combination (`409` on conflict). When the environment requires\napproval, returns `403`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/SegmentName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/EnvironmentId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": false,
          "description": "Optional. Omit or send `{}` to create the default definition shell.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSegmentDefinitionRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created — the segment definition was successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentDefinitionResponse"
                },
                "example": {
                  "entity": {
                    "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
                    "description": "Power users in production",
                    "segment": {
                      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
                      "name": "power-users"
                    },
                    "environment": {
                      "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
                      "name": "Production"
                    },
                    "createdAt": "2025-06-01T12:00:00Z",
                    "status": "ACTIVE"
                  },
                  "governance": {
                    "status": "PASS",
                    "details": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "get": {
        "tags": [
          "Segment Definitions"
        ],
        "operationId": "getSegmentDefinition",
        "summary": "Get a Segment Definition",
        "description": "Requires `environment_id` as a query parameter. Returns a single active Segment Definition\nfor the specified segment in the specified environment. Soft-deleted (`ARCHIVED`)\ndefinitions are not returned by name lookup (`404`); use LIST with `status=ARCHIVED` to\ndiscover them.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/SegmentName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/EnvironmentId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — segment definition returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentDefinition"
                },
                "example": {
                  "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
                  "description": "Power users in production",
                  "segment": {
                    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
                    "name": "power-users"
                  },
                  "environment": {
                    "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
                    "name": "Production"
                  },
                  "createdAt": "2025-06-01T12:00:00Z",
                  "status": "ACTIVE"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "patch": {
        "tags": [
          "Segment Definitions"
        ],
        "operationId": "updateSegmentDefinition",
        "summary": "Update a Segment Definition (partial)",
        "description": "Requires `environment_id` as a query parameter. Partially updates a Segment Definition\nusing JSON Merge Patch semantics (RFC 7396). Only fields present in the request body are\nmodified; omitted fields are left unchanged. JSON `null` clears `description`. See\n`UpdateSegmentDefinitionRequest`.\n\nOnly `ACTIVE` definitions can be updated. Name lookup for non-active definitions returns\n`404`. Returns `409` when a pending change request already exists for this definition.\nWhen the environment requires approval, returns `403`.\n\n**Updatable fields:** `description`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/SegmentName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/EnvironmentId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/merge-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSegmentDefinitionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — segment definition partially updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentDefinitionResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "delete": {
        "tags": [
          "Segment Definitions"
        ],
        "operationId": "deleteSegmentDefinition",
        "summary": "Delete a Segment Definition",
        "description": "Requires `environment_id` as a query parameter. Soft-deletes a Segment Definition by\ntransitioning it to `ARCHIVED`. After delete, GET by name returns `404`; the definition\nremains discoverable via LIST when `status` includes `ARCHIVED`. Returns the OPA governance\nresult. Deleting a definition that is already `ARCHIVED` returns `404`. Returns `409` when a\npending change request already exists (`pendingChangeConflict`), or when keys / flag /\nrule-based-segment dependents block delete (`hasDependents`). When the environment requires\napproval, returns `403`. Accepts optional `comment`/`title` query parameters for the\narchive's audit trail; some workspaces require one or both, and omitting a required one\nreturns `400`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/SegmentName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/EnvironmentId"
          },
          {
            "$ref": "#/components/parameters/CommentQueryParam"
          },
          {
            "$ref": "#/components/parameters/TitleQueryParam"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — segment definition deleted. Returns the governance result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteResponse"
                },
                "example": {
                  "governance": {
                    "status": "PASS",
                    "details": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/segment-definitions/{segment-name}/keys": {
      "get": {
        "tags": [
          "Segment Definitions"
        ],
        "operationId": "listSegmentDefinitionKeys",
        "summary": "List Segment Definition Keys",
        "description": "Requires `environment_id` as a query parameter. Returns a paginated list of membership keys\nfor the specified active Segment Definition in the specified environment. Page size is\ncapped at 100.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/SegmentName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/EnvironmentId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          },
          {
            "$ref": "#/components/parameters/PaginationLimitParam"
          },
          {
            "$ref": "#/components/parameters/PaginationOffsetParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — paginated list of membership keys returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentDefinitionKeyListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "post": {
        "tags": [
          "Segment Definitions"
        ],
        "operationId": "addSegmentDefinitionKeys",
        "summary": "Add Segment Definition Keys",
        "description": "Requires `environment_id` as a query parameter. Adds membership keys to the Segment\nDefinition. When `replace=true`, the submitted list replaces the existing membership (an\nempty `keys` array clears membership); when `false` (default), keys are merged and an empty\nlist is rejected. At most 10000 keys per request. Only `ACTIVE` definitions accept key\nmutations; name lookup for non-active definitions returns `404`. When the environment\nrequires approval, returns `403`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/SegmentName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/EnvironmentId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          },
          {
            "name": "replace",
            "in": "query",
            "required": false,
            "description": "When `true`, replace the entire key membership with the submitted list (including an\nempty list to clear). When `false` (default), add the submitted keys without removing\nexisting ones.\n",
            "schema": {
              "type": "boolean",
              "default": false,
              "example": false
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SegmentDefinitionKeysAddRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — keys added (or membership replaced when `replace=true`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentDefinitionKeysMutationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/segment-definitions/{segment-name}/keys/remove": {
      "post": {
        "tags": [
          "Segment Definitions"
        ],
        "operationId": "removeSegmentDefinitionKeys",
        "summary": "Remove Segment Definition Keys",
        "description": "Requires `environment_id` as a query parameter. Removes the submitted membership keys from\nthe Segment Definition. Keys that are not currently members are ignored. At most 10000 keys\nper request. Only `ACTIVE` definitions accept key mutations; name lookup for non-active\ndefinitions returns `404`. When the environment requires approval, returns `403`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/SegmentName"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/EnvironmentId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SegmentDefinitionKeysRemoveRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — keys removed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentDefinitionKeysMutationResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/environments": {
      "post": {
        "tags": [
          "Environments"
        ],
        "operationId": "createEnvironment",
        "summary": "Create an Environment",
        "description": "Creates a new Environment in the specified project workspace. The environment name must be\nunique within the project.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateEnvironmentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created — the environment was successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnvironmentResponse"
                },
                "example": {
                  "entity": {
                    "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
                    "name": "Production",
                    "isProduction": true,
                    "createdAt": "2025-06-01T12:00:00Z",
                    "status": "ACTIVE"
                  },
                  "governance": {
                    "status": "PASS",
                    "details": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "get": {
        "tags": [
          "Environments"
        ],
        "operationId": "listEnvironments",
        "summary": "List Environments",
        "description": "Returns a paginated list of Environments in the specified project workspace.\nDefaults to active environments (`status` defaults to `[ACTIVE]`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          },
          {
            "$ref": "#/components/parameters/PaginationLimitParam"
          },
          {
            "$ref": "#/components/parameters/PaginationOffsetParam"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by lifecycle status. Defaults to `[ACTIVE]`. Explicit values replace the default.\n",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "ACTIVE",
                  "ARCHIVED"
                ]
              },
              "default": [
                "ACTIVE"
              ]
            },
            "style": "form",
            "explode": true,
            "example": [
              "ACTIVE"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "OK — paginated list of environments returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnvironmentListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/environments/{environment-id}": {
      "get": {
        "tags": [
          "Environments"
        ],
        "operationId": "getEnvironment",
        "summary": "Get an Environment",
        "description": "Returns a single Environment by its system-assigned identifier. Unlike list, this endpoint\nreturns the environment regardless of lifecycle status (`ACTIVE` or `ARCHIVED`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/EnvironmentIdPath"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — environment returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Environment"
                },
                "example": {
                  "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
                  "name": "Production",
                  "isProduction": true,
                  "createdAt": "2025-06-01T12:00:00Z",
                  "status": "ACTIVE"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "patch": {
        "tags": [
          "Environments"
        ],
        "operationId": "updateEnvironment",
        "summary": "Update an Environment (partial)",
        "description": "Partially updates an Environment using JSON Merge Patch semantics (RFC 7396). Only fields\npresent in the request body are modified; omitted fields are left unchanged. Sending `null`\nfor `name` or `isProduction` is rejected with `400`.\n\nOnly `ACTIVE` environments can be updated. Patching an archived environment returns `404`.\nRenaming to a name already used in the project returns `409`.\n\n**Updatable fields:** `name`, `isProduction`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/EnvironmentIdPath"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/merge-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateEnvironmentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — environment updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnvironmentResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "delete": {
        "tags": [
          "Environments"
        ],
        "operationId": "deleteEnvironment",
        "summary": "Delete an Environment",
        "description": "Soft-deletes an Environment by transitioning it to `ARCHIVED`. The environment remains\nretrievable via GET by id and via LIST when `status` includes `ARCHIVED`. Returns the OPA\ngovernance result for the operation. Deleting an environment that is already `ARCHIVED`\nreturns `404`. Deleting an environment that has active dependents returns `409`\n(`hasDependents`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/EnvironmentIdPath"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — environment deleted. Returns the governance result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteResponse"
                },
                "example": {
                  "governance": {
                    "status": "PASS",
                    "details": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/traffic-types": {
      "get": {
        "tags": [
          "Traffic Types"
        ],
        "operationId": "listTrafficTypes",
        "summary": "List Traffic Types",
        "description": "Returns a paginated list of Traffic Types in the specified project workspace.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          },
          {
            "$ref": "#/components/parameters/PaginationLimitParam"
          },
          {
            "$ref": "#/components/parameters/PaginationOffsetParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — paginated list of traffic types returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrafficTypeListResponse"
                },
                "example": {
                  "data": [
                    {
                      "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
                      "name": "user"
                    },
                    {
                      "id": "bd3fc9a1-0d4b-12fe-984d-f345bcbbe430",
                      "name": "account"
                    }
                  ],
                  "limit": 100,
                  "offset": 0,
                  "totalCount": 2
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/event-types": {
      "get": {
        "tags": [
          "Event Types"
        ],
        "operationId": "listEventTypes",
        "summary": "List Event Types",
        "description": "Returns a paginated list of Event Types in the specified project workspace, ordered by id.\nResults can be filtered by id substring or traffic type.\n\nEvent types are only known from events actually received, and only the last 30 days are\nconsidered: an event type that has received no events in that window is not returned.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          },
          {
            "$ref": "#/components/parameters/PaginationLimitParam"
          },
          {
            "$ref": "#/components/parameters/PaginationOffsetParam"
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Case-insensitive substring match on the event type id. Event types have no separate\ndisplay name, so this filters on the same value returned as `id`.\n",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "traffic_type",
            "in": "query",
            "required": false,
            "description": "Filter to event types associated with the given traffic type, by id or name. A traffic\ntype outside the requesting workspace matches nothing.\n",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK — paginated list of event types returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventTypeListResponse"
                },
                "example": {
                  "data": [
                    {
                      "id": "purchase",
                      "trafficTypes": [
                        {
                          "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
                          "name": "user"
                        }
                      ]
                    }
                  ],
                  "limit": 100,
                  "offset": 0,
                  "totalCount": 1
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/event-types/{event-type-id}": {
      "get": {
        "tags": [
          "Event Types"
        ],
        "operationId": "getEventType",
        "summary": "Get an Event Type",
        "description": "Returns a single Event Type by its id (the ingestion-assigned event name). An event type\nthat exists but has no traffic type in scope for the requesting workspace is hidden as a\n`404`, to avoid leaking cross-workspace existence.\n\nAs with the list operation, only the last 30 days of received events are considered, so an\nevent type that has been idle longer than that also returns `404`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeIdPath"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — event type returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventType"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/experiments": {
      "post": {
        "tags": [
          "Experiments"
        ],
        "operationId": "createExperiment",
        "summary": "Create an Experiment",
        "description": "Creates a new Experiment in the specified project workspace. Requires `environment_id`.\nThe parent must exist in that environment (`404` if missing). `parent.type` `CONFIG`\nreturns `404` in v1. Duplicate `name` returns `409`. Do not send `assignmentSource`\n(`400` if present). The server infers or creates the cloud assignment source for the\nproject and `parent.type`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          },
          {
            "$ref": "#/components/parameters/RequiredEnvironmentIdParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateExperimentRequest"
              },
              "examples": {
                "featureFlag": {
                  "summary": "Feature Flag experiment",
                  "value": {
                    "parent": {
                      "type": "FEATURE_FLAG",
                      "name": "checkout-flag"
                    },
                    "name": "checkout-experiment",
                    "hypothesis": "Checkout conversion increases with treatment on.",
                    "startAt": "2025-06-01T12:00:00Z",
                    "endAt": "2025-07-01T12:00:00Z",
                    "baselineTreatment": "off",
                    "comparisonTreatments": [
                      "on"
                    ],
                    "keyMetrics": [
                      "a1b2c3d4-e5f6-7890-abcd-ef1234567892"
                    ],
                    "owners": [
                      {
                        "type": "USER",
                        "id": "xM5qi75eQYmdgJYfwNoHEQ"
                      }
                    ]
                  }
                },
                "aiConfig": {
                  "summary": "AI Config experiment",
                  "value": {
                    "parent": {
                      "type": "AI_CONFIG",
                      "name": "checkout-prompt"
                    },
                    "name": "prompt-experiment",
                    "hypothesis": "New prompt improves task success.",
                    "startAt": "2025-06-01T12:00:00Z",
                    "endAt": "2025-07-01T12:00:00Z",
                    "baselineTreatment": "off",
                    "comparisonTreatments": [
                      "on"
                    ],
                    "owners": [
                      {
                        "type": "TEAM",
                        "id": "platform-team"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created — the experiment was successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExperimentResponse"
                },
                "examples": {
                  "featureFlag": {
                    "summary": "Feature Flag experiment",
                    "value": {
                      "entity": {
                        "type": "EXPERIMENT",
                        "id": "01JAFXNTQHH8QTPTWYSG8H04Y5",
                        "parent": {
                          "type": "FEATURE_FLAG",
                          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                          "name": "checkout-flag"
                        },
                        "name": "checkout-experiment",
                        "description": null,
                        "hypothesis": "Checkout conversion increases with treatment on.",
                        "environment": {
                          "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
                          "name": "Production"
                        },
                        "trafficType": {
                          "id": "a707c5af-94c1-4ca1-99dc-f0e72981c9ec",
                          "name": "user"
                        },
                        "startAt": "2025-06-01T12:00:00Z",
                        "endAt": "2025-07-01T12:00:00Z",
                        "baselineTreatment": "off",
                        "comparisonTreatments": [
                          "on"
                        ],
                        "keyMetrics": [
                          {
                            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
                            "name": "conversion"
                          }
                        ],
                        "supportingMetrics": [],
                        "tags": [
                          {
                            "id": "checkout",
                            "type": "TAG",
                            "name": "checkout"
                          }
                        ],
                        "owners": [
                          {
                            "type": "USER",
                            "id": "xM5qi75eQYmdgJYfwNoHEQ"
                          }
                        ],
                        "status": "ACTIVE",
                        "createdAt": "2025-06-01T12:00:00Z",
                        "modifiedAt": "2025-06-01T12:00:00Z"
                      },
                      "governance": {
                        "status": "NONE",
                        "details": []
                      }
                    }
                  },
                  "aiConfig": {
                    "summary": "AI Config experiment",
                    "value": {
                      "entity": {
                        "type": "EXPERIMENT",
                        "id": "01JAFXNTQHH8QTPTWYSG8H04Y6",
                        "parent": {
                          "type": "AI_CONFIG",
                          "id": "01KPEXA6KN4CZK4D3YCTYJR864",
                          "name": "checkout-prompt"
                        },
                        "name": "prompt-experiment",
                        "description": null,
                        "hypothesis": "New prompt improves task success.",
                        "environment": {
                          "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
                          "name": "Production"
                        },
                        "trafficType": {
                          "id": "a707c5af-94c1-4ca1-99dc-f0e72981c9ec",
                          "name": "user"
                        },
                        "startAt": "2025-06-01T12:00:00Z",
                        "endAt": "2025-07-01T12:00:00Z",
                        "baselineTreatment": "off",
                        "comparisonTreatments": [
                          "on"
                        ],
                        "keyMetrics": [],
                        "supportingMetrics": [],
                        "tags": [],
                        "owners": [
                          {
                            "type": "TEAM",
                            "id": "platform-team"
                          }
                        ],
                        "status": "ACTIVE",
                        "createdAt": "2025-06-01T12:00:00Z",
                        "modifiedAt": "2025-06-01T12:00:00Z"
                      },
                      "governance": {
                        "status": "NONE",
                        "details": []
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "get": {
        "tags": [
          "Experiments"
        ],
        "operationId": "listExperiments",
        "summary": "List Experiments",
        "description": "Returns a paginated list of Experiments in the specified project workspace.\nDefaults to active experiments (`status` defaults to `[ACTIVE]`). Query `parent_type` is\nrequired. Optional `environment_id` filters to one environment.\nOptional `parent_name` filters by parent name for that type (Feature Flag, AI Config,\nor Config). Unknown or mismatched `parent_name` returns `404`. `name` is the experiment\ntitle. `parent_type=CONFIG` returns `404` in v1. Warehouse-native experiments are not\nreturned in v1.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          },
          {
            "$ref": "#/components/parameters/ExperimentParentTypeParam"
          },
          {
            "$ref": "#/components/parameters/OptionalEnvironmentIdParam"
          },
          {
            "name": "parent_name",
            "in": "query",
            "required": false,
            "description": "Filter to this parent name. When `parent_type` is `FEATURE_FLAG`, this is a Feature\nFlag name; when `AI_CONFIG`, an AI Config name; when `CONFIG`, a Config name.\nUnknown name, or a name that is not that parent kind, returns `404`. `name` is\nstill the experiment title.\n",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z][-_A-Za-z0-9]*$",
              "maxLength": 100,
              "example": "checkout-flag"
            }
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Filter by experiment name. Used with `match_type`.",
            "schema": {
              "type": "string",
              "maxLength": 250,
              "example": "checkout-experiment"
            }
          },
          {
            "name": "match_type",
            "in": "query",
            "required": false,
            "description": "How `name` is matched. Ignored when `name` is omitted.",
            "schema": {
              "type": "string",
              "enum": [
                "starts_with",
                "contains",
                "exact"
              ],
              "default": "contains",
              "example": "contains"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by lifecycle status. Defaults to `[ACTIVE]`.",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ExperimentStatus"
              },
              "default": [
                "ACTIVE"
              ]
            },
            "style": "form",
            "explode": true,
            "example": [
              "ACTIVE"
            ]
          },
          {
            "name": "tags",
            "in": "query",
            "required": false,
            "description": "Filter to experiments that have any of the specified tags (by tag name).",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "$ref": "#/components/parameters/PaginationLimitParam"
          },
          {
            "$ref": "#/components/parameters/PaginationOffsetParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — paginated list of experiments returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExperimentListResponse"
                },
                "example": {
                  "data": [
                    {
                      "type": "EXPERIMENT",
                      "id": "01JAFXNTQHH8QTPTWYSG8H04Y5",
                      "parent": {
                        "type": "FEATURE_FLAG",
                        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                        "name": "checkout-flag"
                      },
                      "name": "checkout-experiment",
                      "description": null,
                      "hypothesis": "Checkout conversion increases with treatment on.",
                      "environment": {
                        "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
                        "name": "Production"
                      },
                      "trafficType": {
                        "id": "a707c5af-94c1-4ca1-99dc-f0e72981c9ec",
                        "name": "user"
                      },
                      "startAt": "2025-06-01T12:00:00Z",
                      "endAt": "2025-07-01T12:00:00Z",
                      "baselineTreatment": "off",
                      "comparisonTreatments": [
                        "on"
                      ],
                      "keyMetrics": [
                        {
                          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
                          "name": "conversion"
                        }
                      ],
                      "supportingMetrics": [],
                      "tags": [
                        {
                          "id": "checkout",
                          "type": "TAG",
                          "name": "checkout"
                        }
                      ],
                      "owners": [
                        {
                          "type": "USER",
                          "id": "xM5qi75eQYmdgJYfwNoHEQ"
                        }
                      ],
                      "status": "ACTIVE",
                      "createdAt": "2025-06-01T12:00:00Z",
                      "modifiedAt": "2025-06-15T09:30:00Z"
                    }
                  ],
                  "limit": 100,
                  "offset": 0,
                  "totalCount": 1
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/experiments/{experiment-id}": {
      "get": {
        "tags": [
          "Experiments"
        ],
        "operationId": "getExperiment",
        "summary": "Get an Experiment",
        "description": "Returns a single Experiment by its system-assigned identifier. Unlike list, this endpoint\nreturns the experiment regardless of lifecycle status (`ACTIVE`, `PAUSED`, `ARCHIVED`, or\n`COMPLETED`). `CONFIG` and warehouse-native experiments return `404` in v1.\n`assignmentSource` is omitted.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ExperimentIdPath"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — experiment returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Experiment"
                },
                "examples": {
                  "featureFlag": {
                    "summary": "Feature Flag experiment",
                    "value": {
                      "type": "EXPERIMENT",
                      "id": "01JAFXNTQHH8QTPTWYSG8H04Y5",
                      "parent": {
                        "type": "FEATURE_FLAG",
                        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                        "name": "checkout-flag"
                      },
                      "name": "checkout-experiment",
                      "description": null,
                      "hypothesis": "Checkout conversion increases with treatment on.",
                      "environment": {
                        "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
                        "name": "Production"
                      },
                      "trafficType": {
                        "id": "a707c5af-94c1-4ca1-99dc-f0e72981c9ec",
                        "name": "user"
                      },
                      "startAt": "2025-06-01T12:00:00Z",
                      "endAt": "2025-07-01T12:00:00Z",
                      "baselineTreatment": "off",
                      "comparisonTreatments": [
                        "on"
                      ],
                      "keyMetrics": [
                        {
                          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
                          "name": "conversion"
                        }
                      ],
                      "supportingMetrics": [],
                      "tags": [
                        {
                          "id": "checkout",
                          "type": "TAG",
                          "name": "checkout"
                        }
                      ],
                      "owners": [
                        {
                          "type": "USER",
                          "id": "xM5qi75eQYmdgJYfwNoHEQ"
                        }
                      ],
                      "status": "ACTIVE",
                      "createdAt": "2025-06-01T12:00:00Z",
                      "modifiedAt": "2025-06-15T09:30:00Z"
                    }
                  },
                  "aiConfig": {
                    "summary": "AI Config experiment",
                    "value": {
                      "type": "EXPERIMENT",
                      "id": "01JAFXNTQHH8QTPTWYSG8H04Y6",
                      "parent": {
                        "type": "AI_CONFIG",
                        "id": "01KPEXA6KN4CZK4D3YCTYJR864",
                        "name": "checkout-prompt"
                      },
                      "name": "prompt-experiment",
                      "description": null,
                      "hypothesis": "New prompt improves task success.",
                      "environment": {
                        "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
                        "name": "Production"
                      },
                      "trafficType": {
                        "id": "a707c5af-94c1-4ca1-99dc-f0e72981c9ec",
                        "name": "user"
                      },
                      "startAt": "2025-06-01T12:00:00Z",
                      "endAt": "2025-07-01T12:00:00Z",
                      "baselineTreatment": "off",
                      "comparisonTreatments": [
                        "on"
                      ],
                      "keyMetrics": [],
                      "supportingMetrics": [],
                      "tags": [],
                      "owners": [
                        {
                          "type": "TEAM",
                          "id": "platform-team"
                        }
                      ],
                      "status": "ACTIVE",
                      "createdAt": "2025-06-01T12:00:00Z",
                      "modifiedAt": "2025-06-15T09:30:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "patch": {
        "tags": [
          "Experiments"
        ],
        "operationId": "updateExperiment",
        "summary": "Update an Experiment (partial)",
        "description": "Partially updates an Experiment using JSON Merge Patch (RFC 7396,\n`Content-Type: application/merge-patch+json`). Fields omitted from the body are left\nunchanged. JSON `null` (or `[]` for arrays) clears `description`, `hypothesis`,\n`keyMetrics`, `supportingMetrics`, and `tags`. `name`, `startAt`, `endAt`, `baselineTreatment`,\n`comparisonTreatments`, and `status` cannot be cleared: omit the field to\nleave it unchanged; JSON `null` (or `[]` for `comparisonTreatments`) returns `400`.\nParent and environment cannot be changed. Renaming to a name already used in the\nproject returns `409`. `CONFIG` and warehouse-native experiments return `404` in v1.\n\n**Updatable fields:** `name`, `description`, `hypothesis`, `rule`, `startAt`, `endAt`,\n`baselineTreatment`, `comparisonTreatments`, `keyMetrics`,\n`supportingMetrics`, `tags`, `owners`, `status`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ExperimentIdPath"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/merge-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateExperimentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — experiment updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExperimentResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "delete": {
        "tags": [
          "Experiments"
        ],
        "operationId": "deleteExperiment",
        "summary": "Delete an Experiment",
        "description": "Permanently deletes an Experiment. This is a hard delete — the experiment is removed, is\nnot recoverable, and afterward a `GET` by id returns `404` and it no longer appears in\n`LIST`. It does not set `status: ARCHIVED`. The parent Feature Flag, AI Config, or Config\nis not deleted. `CONFIG` and warehouse-native experiments return `404` in v1.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ExperimentIdPath"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — experiment deleted. Returns the governance result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteResponse"
                },
                "example": {
                  "governance": {
                    "status": "NONE",
                    "details": []
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/metrics": {
      "post": {
        "tags": [
          "Metrics"
        ],
        "operationId": "createMetric",
        "summary": "Create a Metric",
        "description": "Creates a new Metric in the specified project workspace. The metric name must be unique\nwithin the project and is immutable after creation.\n\n**Validation (beyond what the request schema enforces):** a `filterEventType` may not target\nthe same event type as any `baseEventTypes` entry **unless** their property filters differ;\nan exact overlap is rejected with `400` (`errorType: filterEventMatchesBaseEvent`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateMetricRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created — the metric was successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/MetricConflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "get": {
        "tags": [
          "Metrics"
        ],
        "operationId": "listMetrics",
        "summary": "List Metrics",
        "description": "Returns a paginated list of Metrics in the specified project workspace. Results can be\nfiltered by name, traffic type, event type, tags, or metric identifiers, and are sorted by\nname. Only live metrics are returned; deleted metrics are removed permanently and never\nappear in the list.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          },
          {
            "$ref": "#/components/parameters/PaginationLimitParam"
          },
          {
            "$ref": "#/components/parameters/PaginationOffsetParam"
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Case-insensitive substring match on metric name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "traffic_type_id",
            "in": "query",
            "required": false,
            "description": "Filter to metrics of the given traffic type (by id).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "event_type_ids",
            "in": "query",
            "required": false,
            "description": "Filter to metrics that measure any of the given event types (matched against the\nmetric's `baseEventTypes[].eventTypeId`). Repeat the parameter to pass multiple.\n",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "tags",
            "in": "query",
            "required": false,
            "description": "Filter to metrics that have any of the specified tags (by tag name).",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "description": "Filter to the specified metric ids.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "sort_order",
            "in": "query",
            "required": false,
            "description": "Sort direction by name.",
            "schema": {
              "type": "string",
              "enum": [
                "ASCENDING",
                "DESCENDING"
              ],
              "default": "ASCENDING"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK — paginated list of metrics returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/v4/metrics/{metric-id}": {
      "get": {
        "tags": [
          "Metrics"
        ],
        "operationId": "getMetric",
        "summary": "Get a Metric",
        "description": "Returns a single Metric by its system-assigned identifier. A deleted metric is removed\npermanently, so a `GET` for one returns `404`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/MetricIdPath"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — metric returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Metric"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "patch": {
        "tags": [
          "Metrics"
        ],
        "operationId": "updateMetric",
        "summary": "Update a Metric (partial)",
        "description": "Partially updates a Metric using JSON Merge Patch (RFC 7386,\n`Content-Type: application/merge-patch+json`). Fields omitted from the body are left\nunchanged; sending `null` clears a nullable field. Arrays (`baseEventTypes`, `tags`,\n`owners`) are replaced in full — there is no element-level merge, so to add or remove one\nentry, send the complete list. `name` and `trafficType` are immutable.\n\nBecause array fields are replaced in full and the input shapes differ from the rich objects\nreturned on read, appending to an array means re-sending the existing entries in **input**\nshape: `tags` as `{ name }` (from each tag's `name`), `owners` as `{ type, id | email }` for\nusers or `{ type, identifier }` for groups (from each owner's `id`/`identifier`). Example — a\nmetric that returns `tags: [{ type, id, name: \"checkout\" }]`, adding `q3`:\n`{ \"tags\": [ { \"name\": \"checkout\" }, { \"name\": \"q3\" } ] }`.\n\nUpdatable fields: `description`, `format`, `aggregation`, `isPositive`, `spread`,\n`baseEventTypes`, `filterEventType`, `triggerEventType`, `tags`, `owners`, `cap`.\n\n**Validation (beyond what the request schema enforces):** a `filterEventType` may not target\nthe same event type as any `baseEventTypes` entry **unless** their property filters differ;\nan exact overlap is rejected with `400` (`errorType: filterEventMatchesBaseEvent`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/MetricIdPath"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/merge-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateMetricRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — metric updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/MetricConflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      },
      "delete": {
        "tags": [
          "Metrics"
        ],
        "operationId": "deleteMetric",
        "summary": "Delete a Metric",
        "description": "Permanently deletes a Metric. This is a hard delete — the metric is removed, is not\nrecoverable, and afterward a `GET` by id returns `404` and it no longer appears in `LIST`.\nThere is no archive or restore. Any references to the metric (for example from experiments'\nkey-metric lists) are cleaned up as part of the delete.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/MetricIdPath"
          },
          {
            "$ref": "#/components/parameters/AccountId"
          },
          {
            "$ref": "#/components/parameters/OrganizationIdentifier"
          },
          {
            "$ref": "#/components/parameters/ProjectIdentifier"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — metric permanently deleted. Returns the governance result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "FeatureFlag": {
        "type": "object",
        "description": "A workspace-scoped Feature Flag entity.",
        "required": [
          "id",
          "name",
          "trafficType",
          "createdAt",
          "status",
          "tags",
          "owners"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique system-assigned identifier for the feature flag.",
            "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          },
          "name": {
            "type": "string",
            "description": "Unique feature flag name within the project. Immutable after creation — use this as the\npath parameter in subsequent requests.\n",
            "example": "my-new-flag"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Human-readable description of this feature flag.",
            "example": "Controls the new checkout experience"
          },
          "trafficType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NamedReference"
              }
            ],
            "description": "Reference to the traffic type used to bucket users."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 timestamp when the feature flag was created.",
            "example": "2025-06-01T12:00:00Z"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "ARCHIVED"
            ],
            "description": "Lifecycle status of the feature flag.\n- `ACTIVE` — flag is live.\n- `ARCHIVED` — flag is no longer active and is read-only.\n",
            "example": "ACTIVE"
          },
          "rolloutStatus": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NamedReference"
              }
            ],
            "type": "object",
            "nullable": true,
            "description": "Rollout status assigned to this feature flag.\n\nThis field is omitted or `null` when no rollout status is assigned. It cannot be set\nwhen creating a feature flag. New feature flags use the workspace default rollout\nstatus. Use PATCH to change it.\n"
          },
          "tags": {
            "type": "array",
            "description": "Tags associated with this feature flag.",
            "items": {
              "$ref": "#/components/schemas/NamedReference"
            }
          },
          "owners": {
            "type": "array",
            "description": "Users or teams that own this feature flag. `USER` owners include `email`; `GROUP`\nowners do not.\n",
            "items": {
              "$ref": "#/components/schemas/OwnerReference"
            }
          }
        },
        "example": {
          "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"
            }
          ]
        }
      },
      "FeatureFlagResponse": {
        "type": "object",
        "description": "Mutation response (create, update, archive, unarchive): entity plus OPA governance.\n",
        "required": [
          "entity",
          "governance"
        ],
        "properties": {
          "entity": {
            "$ref": "#/components/schemas/FeatureFlag"
          },
          "governance": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GovernanceResult"
              }
            ],
            "description": "OPA governance result for the mutation."
          }
        }
      },
      "FeatureFlagListResponse": {
        "type": "object",
        "description": "Paginated list of Feature Flags matching the query.",
        "required": [
          "data",
          "limit",
          "offset",
          "totalCount"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FeatureFlag"
            }
          },
          "limit": {
            "type": "integer",
            "description": "The page size used for this response.",
            "example": 100
          },
          "offset": {
            "type": "integer",
            "description": "The number of items skipped before the first result.",
            "example": 0
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of feature flags matching the query.",
            "example": 42
          }
        }
      },
      "CreateFeatureFlagRequest": {
        "type": "object",
        "description": "Request body for creating a new Feature Flag.",
        "required": [
          "name",
          "trafficType"
        ],
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^[A-Za-z][-_A-Za-z0-9]*$",
            "maxLength": 100,
            "description": "Unique feature flag name within the project. Immutable after creation.",
            "example": "my-new-flag"
          },
          "description": {
            "type": "string",
            "description": "Human-readable description of this feature flag.",
            "example": "Controls the new checkout experience"
          },
          "trafficType": {
            "type": "string",
            "description": "Traffic type used to bucket users, identified by its name (for example `user` or\n`account`). Immutable after creation.\n",
            "example": "user"
          },
          "tags": {
            "type": "array",
            "description": "Initial tags to associate with the feature flag.",
            "items": {
              "$ref": "#/components/schemas/TagReferenceInput"
            }
          },
          "owners": {
            "type": "array",
            "description": "Initial owners (users or teams) for this feature flag. If omitted or empty, the\nproject's default admin team is assigned.\n",
            "items": {
              "$ref": "#/components/schemas/OwnerReferenceInput"
            }
          }
        },
        "example": {
          "name": "my-new-flag",
          "description": "Controls the new checkout experience",
          "trafficType": "user",
          "tags": [
            {
              "name": "backend"
            }
          ],
          "owners": [
            {
              "type": "USER",
              "email": "alice@example.com"
            }
          ]
        }
      },
      "UpdateFeatureFlagRequest": {
        "type": "object",
        "description": "JSON Merge Patch body (RFC 7396) for updating a Feature Flag. All fields are optional. Omit a\nfield to leave it unchanged. JSON `null` (or `[]` for arrays) clears `description`, `tags`,\nand `owners`. `rolloutStatus` cannot be cleared: omit to keep; JSON `null` returns `400`.\n",
        "properties": {
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Updated human-readable description.",
            "example": "Updated feature flag description"
          },
          "tags": {
            "type": "array",
            "nullable": true,
            "description": "Replacement tag list.",
            "items": {
              "$ref": "#/components/schemas/TagReferenceInput"
            }
          },
          "owners": {
            "type": "array",
            "nullable": true,
            "description": "Replacement owner list.",
            "items": {
              "$ref": "#/components/schemas/OwnerReferenceInput"
            }
          },
          "rolloutStatus": {
            "type": "object",
            "description": "Updated rollout status, identified by its system-assigned `id`. Omit to keep; JSON `null` returns `400`.",
            "required": [
              "id"
            ],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "System-assigned identifier for the rollout status.",
                "example": "ad2eb8f0-9c3a-11ed-873c-e234abaad319"
              }
            },
            "example": {
              "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319"
            }
          }
        },
        "example": {
          "description": "Updated feature flag description",
          "tags": [
            {
              "name": "backend"
            }
          ],
          "owners": [
            {
              "type": "GROUP",
              "identifier": "platform-team"
            }
          ]
        }
      },
      "ArchiveUnarchiveFeatureFlagRequest": {
        "type": "object",
        "description": "Optional metadata supplied when archiving or unarchiving a feature flag.",
        "properties": {
          "comment": {
            "type": "string",
            "description": "Optional comment recorded with the action.",
            "example": "Flag no longer needed after Q3 cleanup"
          }
        },
        "example": {
          "comment": "Flag no longer needed after Q3 cleanup"
        }
      },
      "NamedReference": {
        "type": "object",
        "description": "Generic reference to another resource, returned in responses. `id` is the stable\npublic identifier and `name` is the human-readable label.\n",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the referenced resource.",
            "example": "ad2eb8f0-9c3a-11ed-873c-e234abaad322"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name of the referenced resource.",
            "example": "backend"
          }
        },
        "example": {
          "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad322",
          "name": "backend"
        }
      },
      "OwnerReference": {
        "type": "object",
        "description": "Reference to an owner (user or group), returned in responses. Extends the generic reference\nwith an optional `email`: a `USER` owner MAY carry `email` where the resource populates it;\na `GROUP` owner never has one. Use `id` for subsequent API calls; `name`/`email` are\ninformational (they let clients that keyed on a user's email at write time correlate the\nresponse without a lookup). Shared across FME v4 resources that expose owners.\n",
        "required": [
          "id",
          "type",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the owner — the Harness user id (for `USER`) or group id (for `GROUP`).",
            "example": "xM5qi75eQYmdgJYfwNoHEQ"
          },
          "type": {
            "type": "string",
            "enum": [
              "USER",
              "GROUP"
            ],
            "description": "Owner kind.",
            "example": "USER"
          },
          "name": {
            "type": "string",
            "description": "Human-readable display name of the user or group.",
            "example": "Alice Example"
          },
          "email": {
            "type": "string",
            "format": "email",
            "nullable": true,
            "description": "Email address of the owner. Optionally populated for `USER` owners where the resource\nsupports it; `null`/absent for `GROUP` owners and for resources that do not return it.\n",
            "example": "alice@example.com"
          }
        },
        "example": {
          "id": "xM5qi75eQYmdgJYfwNoHEQ",
          "type": "USER",
          "name": "Alice Example",
          "email": "alice@example.com"
        }
      },
      "ErrorDetail": {
        "type": "object",
        "description": "Details about a single sub-error.",
        "required": [
          "errorType",
          "title"
        ],
        "properties": {
          "errorType": {
            "type": "string",
            "description": "Machine-readable error type for this specific error.",
            "example": "requiredField"
          },
          "title": {
            "type": "string",
            "description": "Short summary of this specific error.",
            "example": "Required field missing"
          },
          "detail": {
            "type": "string",
            "description": "Detailed explanation of this specific error.",
            "example": "Field 'name' is required"
          },
          "field": {
            "type": "string",
            "description": "Name of the request field this error applies to, when the error is field-specific\n(for example a validation failure). Omitted for errors not tied to a single field.\n",
            "example": "name"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Standard error response following RFC 7807 Problem Details format (Harness ADR 57).\n",
        "required": [
          "type",
          "status",
          "title",
          "errorType"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "URI reference to documentation for this error type.",
            "example": "https://developer.harness.io/docs/api-reference/errors#validation-error"
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code.",
            "example": 400
          },
          "title": {
            "type": "string",
            "description": "Short human-readable summary of the problem.",
            "example": "Validation Error"
          },
          "errorType": {
            "type": "string",
            "description": "Machine-readable error type identifier.",
            "example": "validationError"
          },
          "detail": {
            "type": "string",
            "description": "Detailed human-readable explanation specific to this occurrence.",
            "example": "Field 'name' is required and must be a non-empty string"
          },
          "instance": {
            "type": "string",
            "description": "URI reference identifying the specific occurrence (usually the request path).",
            "example": "/v4/feature-flags"
          },
          "errors": {
            "type": "array",
            "description": "List of specific sub-errors (useful for multi-field validation failures). Governance\npolicy failures are also surfaced here — each failing policy is reported as an entry\nwith `errorType: \"governancePolicy\"` — rather than in a separate top-level field.\n",
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            }
          }
        }
      },
      "TagReferenceInput": {
        "type": "object",
        "description": "Tag input used in request bodies. Identified by `name`.",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Tag name.",
            "example": "backend"
          }
        },
        "example": {
          "name": "backend"
        }
      },
      "UserOwnerReferenceInput": {
        "type": "object",
        "description": "User owner input. Prefer `email`; `id` is also accepted for compatibility when the caller\nalready has the Harness user id.\n",
        "required": [
          "type"
        ],
        "anyOf": [
          {
            "required": [
              "email"
            ]
          },
          {
            "required": [
              "id"
            ]
          }
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "USER"
            ],
            "description": "Owner type discriminator. Always `USER`.",
            "example": "USER"
          },
          "id": {
            "type": "string",
            "description": "Harness user id.",
            "example": "xM5qi75eQYmdgJYfwNoHEQ"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "User email address.",
            "example": "alice@example.com"
          }
        },
        "example": {
          "type": "USER",
          "email": "alice@example.com"
        }
      },
      "GroupOwnerReferenceInput": {
        "type": "object",
        "description": "Group owner input.",
        "required": [
          "type",
          "identifier"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "GROUP"
            ],
            "description": "Owner type discriminator. Always `GROUP`.",
            "example": "GROUP"
          },
          "identifier": {
            "type": "string",
            "description": "Group identifier.",
            "example": "platform-team"
          }
        },
        "example": {
          "type": "GROUP",
          "identifier": "platform-team"
        }
      },
      "OwnerReferenceInput": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/UserOwnerReferenceInput"
          },
          {
            "$ref": "#/components/schemas/GroupOwnerReferenceInput"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "USER": "#/components/schemas/UserOwnerReferenceInput",
            "GROUP": "#/components/schemas/GroupOwnerReferenceInput"
          }
        },
        "description": "Owner input. Use `USER` for users and `GROUP` for groups."
      },
      "GovernancePolicyDetail": {
        "type": "object",
        "description": "Per-policy OPA evaluation result.",
        "required": [
          "policyName",
          "status",
          "message"
        ],
        "properties": {
          "policyName": {
            "type": "string",
            "description": "Name of the OPA policy that was evaluated.",
            "example": "require-description"
          },
          "status": {
            "type": "string",
            "enum": [
              "PASS",
              "WARNING",
              "ERROR"
            ],
            "description": "Result of evaluating this specific policy.",
            "example": "WARNING"
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation of the policy result.",
            "example": "Feature flag definition should have a non-empty comment"
          }
        }
      },
      "GovernanceResult": {
        "type": "object",
        "description": "OPA policy evaluation result for the operation. `PASS`, `WARNING`, and `ERROR` mean\ngovernance ran; `NONE` means governance was not evaluated (for example off or not linked).\n",
        "required": [
          "status",
          "details"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "PASS",
              "WARNING",
              "ERROR",
              "NONE"
            ],
            "description": "Overall governance result. `NONE` when governance did not run; otherwise the aggregate\nacross evaluated policies.\n",
            "example": "PASS"
          },
          "details": {
            "type": "array",
            "description": "Per-policy results. Empty array when all policies pass cleanly or when status is `NONE`.",
            "items": {
              "$ref": "#/components/schemas/GovernancePolicyDetail"
            }
          }
        },
        "example": {
          "status": "PASS",
          "details": []
        }
      },
      "DeleteResponse": {
        "type": "object",
        "description": "Response envelope for delete operations. Contains only the OPA governance result — no\nentity is returned. Shared by all FME resources so delete responses are consistent.\n",
        "required": [
          "governance"
        ],
        "properties": {
          "governance": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GovernanceResult"
              }
            ],
            "description": "OPA governance result for the delete operation."
          }
        }
      },
      "Treatment": {
        "type": "object",
        "description": "A single treatment (variation) of the feature flag in this environment.\n",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TreatmentName"
              }
            ],
            "description": "Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods. The reserved name `control` is not allowed.\n",
            "example": "on"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Optional description of this treatment.",
            "example": "The feature flag is on"
          },
          "keys": {
            "type": "array",
            "description": "Keys explicitly assigned to this treatment.",
            "items": {
              "type": "string"
            },
            "example": [
              "123",
              "234"
            ]
          },
          "segments": {
            "type": "array",
            "description": "Standard segment names assigned to this treatment.",
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z][-_A-Za-z0-9]*$",
              "maxLength": 100
            },
            "example": [
              "power-users"
            ]
          },
          "largeSegments": {
            "type": "array",
            "description": "Large segment names assigned to this treatment.",
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z][-_A-Za-z0-9]*$",
              "maxLength": 100
            },
            "example": [
              "enterprise-users"
            ]
          },
          "ruleBasedSegments": {
            "type": "array",
            "description": "Rule-based segment names assigned to this treatment.",
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z][-_A-Za-z0-9]*$",
              "maxLength": 100
            },
            "example": [
              "high-value-users"
            ]
          },
          "configurations": {
            "type": "string",
            "nullable": true,
            "description": "Dynamic configuration attached to this treatment, serialized as a JSON string.\n",
            "example": ""
          }
        },
        "example": {
          "name": "on",
          "description": "The feature flag is on",
          "configurations": ""
        }
      },
      "TreatmentInput": {
        "type": "object",
        "description": "Treatment input used in create and patch request bodies. The default treatment is selected\nwith the request-level `defaultTreatment` field.\n",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TreatmentName"
              }
            ],
            "description": "Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods. The reserved name `control` is not allowed.\n",
            "example": "on"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Optional description of this treatment.",
            "example": "The feature flag is on"
          },
          "keys": {
            "type": "array",
            "description": "Keys explicitly assigned to this treatment.",
            "items": {
              "type": "string"
            },
            "example": [
              "123",
              "234"
            ]
          },
          "segments": {
            "type": "array",
            "description": "Standard segment names assigned to this treatment.",
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z][-_A-Za-z0-9]*$",
              "maxLength": 100
            },
            "example": [
              "power-users"
            ]
          },
          "largeSegments": {
            "type": "array",
            "description": "Large segment names assigned to this treatment.",
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z][-_A-Za-z0-9]*$",
              "maxLength": 100
            },
            "example": [
              "enterprise-users"
            ]
          },
          "ruleBasedSegments": {
            "type": "array",
            "description": "Rule-based segment names assigned to this treatment.",
            "items": {
              "type": "string",
              "pattern": "^[A-Za-z][-_A-Za-z0-9]*$",
              "maxLength": 100
            },
            "example": [
              "high-value-users"
            ]
          },
          "configurations": {
            "type": "string",
            "nullable": true,
            "description": "Dynamic configuration attached to this treatment, serialized as a JSON string.\n",
            "example": ""
          }
        },
        "example": {
          "name": "on",
          "description": "The feature flag is on",
          "configurations": ""
        }
      },
      "Distribution": {
        "type": "object",
        "description": "A percentage bucket assigning a share of traffic to a treatment. The treatment name must\nrefer to a treatment in the same definition.\n",
        "required": [
          "treatment",
          "size"
        ],
        "properties": {
          "treatment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TreatmentName"
              }
            ],
            "description": "Treatment name from this definition.",
            "example": "on"
          },
          "size": {
            "type": "integer",
            "format": "int32",
            "minimum": 0,
            "maximum": 100,
            "description": "Percentage of traffic assigned to the treatment (0-100).",
            "example": 75
          }
        },
        "example": {
          "treatment": "on",
          "size": 75
        }
      },
      "DistributionInput": {
        "type": "object",
        "description": "Distribution input used in create and patch request bodies. The treatment name must refer\nto a treatment in the same request/definition.\n",
        "required": [
          "treatment",
          "size"
        ],
        "properties": {
          "treatment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TreatmentName"
              }
            ],
            "description": "Treatment name from this definition.",
            "example": "on"
          },
          "size": {
            "type": "integer",
            "format": "int32",
            "minimum": 0,
            "maximum": 100,
            "description": "Percentage of traffic assigned to the treatment (0-100).",
            "example": 75
          }
        },
        "example": {
          "treatment": "on",
          "size": 75
        }
      },
      "Condition": {
        "type": "object",
        "description": "The matching condition for a targeting rule. Only the `AND` combiner is supported — all\nmatchers must match. `OR` combination is not supported.\n",
        "required": [
          "combiner",
          "matchers"
        ],
        "properties": {
          "combiner": {
            "type": "string",
            "enum": [
              "AND"
            ],
            "description": "Matcher combiner. Only `AND` is supported.",
            "example": "AND"
          },
          "matchers": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/Matcher"
            }
          }
        }
      },
      "Rule": {
        "type": "object",
        "description": "A targeting rule: a condition and the treatment buckets served on match.\n",
        "required": [
          "condition",
          "buckets"
        ],
        "properties": {
          "condition": {
            "$ref": "#/components/schemas/Condition"
          },
          "buckets": {
            "type": "array",
            "minItems": 1,
            "description": "Treatment buckets served when the condition matches. Sizes must sum to 100.\n",
            "items": {
              "$ref": "#/components/schemas/Distribution"
            }
          }
        }
      },
      "ConditionInput": {
        "type": "object",
        "description": "Targeting condition for create/patch request bodies. If `combiner` is omitted, the server\ntreats it as `AND`.\n",
        "required": [
          "matchers"
        ],
        "properties": {
          "combiner": {
            "type": "string",
            "enum": [
              "AND"
            ],
            "default": "AND",
            "description": "Matcher combiner. Only `AND` is supported; defaults to `AND` when omitted.",
            "example": "AND"
          },
          "matchers": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/Matcher"
            }
          }
        }
      },
      "RuleInput": {
        "type": "object",
        "description": "Targeting rule for create/patch request bodies. Buckets use `DistributionInput`.",
        "required": [
          "condition",
          "buckets"
        ],
        "properties": {
          "condition": {
            "$ref": "#/components/schemas/ConditionInput"
          },
          "buckets": {
            "type": "array",
            "minItems": 1,
            "description": "Treatment buckets served when the condition matches. Sizes must sum to 100.\n",
            "items": {
              "$ref": "#/components/schemas/DistributionInput"
            }
          }
        }
      },
      "Matcher": {
        "description": "A matcher within a targeting condition. Discriminated by `type` — each variant requires\nthe value field(s) that type evaluates. `negate` is optional on every variant (`true`\ninverts the result). `attribute` is required when the matcher evaluates a traffic-type\nattribute; omit it only for key-based list/string matchers (`IN_LIST_STRING`,\n`STARTS_WITH_STRING`, `ENDS_WITH_STRING`, `CONTAINS_STRING`, `MATCHES_STRING`).\n",
        "oneOf": [
          {
            "$ref": "#/components/schemas/SegmentMatcher"
          },
          {
            "$ref": "#/components/schemas/SplitMatcher"
          },
          {
            "$ref": "#/components/schemas/BooleanMatcher"
          },
          {
            "$ref": "#/components/schemas/DateMatcher"
          },
          {
            "$ref": "#/components/schemas/BetweenDateMatcher"
          },
          {
            "$ref": "#/components/schemas/SetMatcher"
          },
          {
            "$ref": "#/components/schemas/NumberMatcher"
          },
          {
            "$ref": "#/components/schemas/BetweenNumberMatcher"
          },
          {
            "$ref": "#/components/schemas/InListStringMatcher"
          },
          {
            "$ref": "#/components/schemas/StringListMatcher"
          },
          {
            "$ref": "#/components/schemas/MatchesStringMatcher"
          },
          {
            "$ref": "#/components/schemas/SemverCompareMatcher"
          },
          {
            "$ref": "#/components/schemas/BetweenSemverMatcher"
          },
          {
            "$ref": "#/components/schemas/InListSemverMatcher"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "IN_SEGMENT": "#/components/schemas/SegmentMatcher",
            "IN_LARGE_SEGMENT": "#/components/schemas/SegmentMatcher",
            "IN_RULE_BASED_SEGMENT": "#/components/schemas/SegmentMatcher",
            "IN_SPLIT": "#/components/schemas/SplitMatcher",
            "BOOLEAN": "#/components/schemas/BooleanMatcher",
            "ON_DATE": "#/components/schemas/DateMatcher",
            "ON_OR_AFTER_DATE": "#/components/schemas/DateMatcher",
            "ON_OR_BEFORE_DATE": "#/components/schemas/DateMatcher",
            "BETWEEN_DATE": "#/components/schemas/BetweenDateMatcher",
            "EQUAL_SET": "#/components/schemas/SetMatcher",
            "ANY_OF_SET": "#/components/schemas/SetMatcher",
            "ALL_OF_SET": "#/components/schemas/SetMatcher",
            "PART_OF_SET": "#/components/schemas/SetMatcher",
            "EQUAL_NUMBER": "#/components/schemas/NumberMatcher",
            "LESS_THAN_OR_EQUAL_NUMBER": "#/components/schemas/NumberMatcher",
            "GREATER_THAN_OR_EQUAL_NUMBER": "#/components/schemas/NumberMatcher",
            "BETWEEN_NUMBER": "#/components/schemas/BetweenNumberMatcher",
            "IN_LIST_STRING": "#/components/schemas/InListStringMatcher",
            "STARTS_WITH_STRING": "#/components/schemas/StringListMatcher",
            "ENDS_WITH_STRING": "#/components/schemas/StringListMatcher",
            "CONTAINS_STRING": "#/components/schemas/StringListMatcher",
            "MATCHES_STRING": "#/components/schemas/MatchesStringMatcher",
            "EQUAL_TO_SEMVER": "#/components/schemas/SemverCompareMatcher",
            "GREATER_THAN_OR_EQUAL_TO_SEMVER": "#/components/schemas/SemverCompareMatcher",
            "LESS_THAN_OR_EQUAL_TO_SEMVER": "#/components/schemas/SemverCompareMatcher",
            "BETWEEN_SEMVER": "#/components/schemas/BetweenSemverMatcher",
            "IN_LIST_SEMVER": "#/components/schemas/InListSemverMatcher"
          }
        }
      },
      "SegmentMatcher": {
        "type": "object",
        "additionalProperties": false,
        "description": "Key is in the named standard, large, or rule-based segment.",
        "required": [
          "type",
          "string"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "IN_SEGMENT",
              "IN_LARGE_SEGMENT",
              "IN_RULE_BASED_SEGMENT"
            ]
          },
          "negate": {
            "type": "boolean",
            "example": false
          },
          "string": {
            "type": "string",
            "description": "Segment name.",
            "example": "power-users"
          }
        },
        "example": {
          "type": "IN_SEGMENT",
          "string": "power-users"
        }
      },
      "SplitMatcher": {
        "type": "object",
        "additionalProperties": false,
        "description": "Prerequisite feature-flag (dependency) matcher.",
        "required": [
          "type",
          "depends"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "IN_SPLIT"
            ]
          },
          "negate": {
            "type": "boolean",
            "example": false
          },
          "depends": {
            "$ref": "#/components/schemas/Depends"
          }
        },
        "example": {
          "type": "IN_SPLIT",
          "depends": {
            "splitName": "billing-experience",
            "treatments": [
              "on"
            ]
          }
        }
      },
      "BooleanMatcher": {
        "type": "object",
        "additionalProperties": false,
        "description": "Attribute equals a boolean value.",
        "required": [
          "type",
          "attribute",
          "bool"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "BOOLEAN"
            ]
          },
          "negate": {
            "type": "boolean",
            "example": false
          },
          "attribute": {
            "type": "string",
            "example": "internal"
          },
          "bool": {
            "type": "boolean",
            "example": true
          }
        },
        "example": {
          "type": "BOOLEAN",
          "attribute": "internal",
          "bool": true
        }
      },
      "DateMatcher": {
        "type": "object",
        "additionalProperties": false,
        "description": "Attribute compared to a single epoch-millisecond timestamp.",
        "required": [
          "type",
          "attribute",
          "date"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "ON_DATE",
              "ON_OR_AFTER_DATE",
              "ON_OR_BEFORE_DATE"
            ]
          },
          "negate": {
            "type": "boolean",
            "example": false
          },
          "attribute": {
            "type": "string",
            "example": "signupDate"
          },
          "date": {
            "type": "integer",
            "format": "int64",
            "description": "Epoch milliseconds.",
            "example": 1704067200000
          }
        },
        "example": {
          "type": "ON_OR_AFTER_DATE",
          "attribute": "signupDate",
          "date": 1704067200000
        }
      },
      "BetweenDateMatcher": {
        "type": "object",
        "additionalProperties": false,
        "description": "Attribute falls in an inclusive epoch-millisecond range.",
        "required": [
          "type",
          "attribute",
          "between"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "BETWEEN_DATE"
            ]
          },
          "negate": {
            "type": "boolean",
            "example": false
          },
          "attribute": {
            "type": "string",
            "example": "signupDate"
          },
          "between": {
            "$ref": "#/components/schemas/BetweenNumberAttribute"
          }
        },
        "example": {
          "type": "BETWEEN_DATE",
          "attribute": "signupDate",
          "between": {
            "from": 1704067200000,
            "to": 1735689600000
          }
        }
      },
      "SetMatcher": {
        "type": "object",
        "additionalProperties": false,
        "description": "Attribute set compared to a list of strings.",
        "required": [
          "type",
          "attribute",
          "strings"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "EQUAL_SET",
              "ANY_OF_SET",
              "ALL_OF_SET",
              "PART_OF_SET"
            ]
          },
          "negate": {
            "type": "boolean",
            "example": false
          },
          "attribute": {
            "type": "string",
            "example": "roles"
          },
          "strings": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string"
            },
            "example": [
              "admin",
              "editor"
            ]
          }
        },
        "example": {
          "type": "ANY_OF_SET",
          "attribute": "roles",
          "strings": [
            "admin",
            "editor"
          ]
        }
      },
      "NumberMatcher": {
        "type": "object",
        "additionalProperties": false,
        "description": "Attribute compared to a single int64 number.",
        "required": [
          "type",
          "attribute",
          "number"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "EQUAL_NUMBER",
              "LESS_THAN_OR_EQUAL_NUMBER",
              "GREATER_THAN_OR_EQUAL_NUMBER"
            ]
          },
          "negate": {
            "type": "boolean",
            "example": false
          },
          "attribute": {
            "type": "string",
            "example": "age"
          },
          "number": {
            "type": "integer",
            "format": "int64",
            "example": 10
          }
        },
        "example": {
          "type": "GREATER_THAN_OR_EQUAL_NUMBER",
          "attribute": "age",
          "number": 18
        }
      },
      "BetweenNumberMatcher": {
        "type": "object",
        "additionalProperties": false,
        "description": "Attribute falls in an inclusive numeric range.",
        "required": [
          "type",
          "attribute",
          "between"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "BETWEEN_NUMBER"
            ]
          },
          "negate": {
            "type": "boolean",
            "example": false
          },
          "attribute": {
            "type": "string",
            "example": "age"
          },
          "between": {
            "$ref": "#/components/schemas/BetweenNumberAttribute"
          }
        },
        "example": {
          "type": "BETWEEN_NUMBER",
          "attribute": "age",
          "between": {
            "from": 18,
            "to": 65
          }
        }
      },
      "InListStringMatcher": {
        "type": "object",
        "additionalProperties": false,
        "description": "Value is in a string list. Omit `attribute` to match the key; set `attribute` to match\nthat traffic-type attribute.\n",
        "required": [
          "type",
          "strings"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "IN_LIST_STRING"
            ]
          },
          "negate": {
            "type": "boolean",
            "example": false
          },
          "attribute": {
            "type": "string",
            "example": "country"
          },
          "strings": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string"
            },
            "example": [
              "US",
              "CA"
            ]
          }
        },
        "example": {
          "type": "IN_LIST_STRING",
          "attribute": "country",
          "strings": [
            "US",
            "CA"
          ]
        }
      },
      "StringListMatcher": {
        "type": "object",
        "additionalProperties": false,
        "description": "Attribute (or key, if `attribute` is omitted) starts with, ends with, or contains any of\nthe listed strings.\n",
        "required": [
          "type",
          "strings"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "STARTS_WITH_STRING",
              "ENDS_WITH_STRING",
              "CONTAINS_STRING"
            ]
          },
          "negate": {
            "type": "boolean",
            "example": false
          },
          "attribute": {
            "type": "string",
            "example": "email"
          },
          "strings": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string"
            },
            "example": [
              "@example.com"
            ]
          }
        },
        "example": {
          "type": "ENDS_WITH_STRING",
          "attribute": "email",
          "strings": [
            "@example.com"
          ]
        }
      },
      "MatchesStringMatcher": {
        "type": "object",
        "additionalProperties": false,
        "description": "Attribute (or key, if `attribute` is omitted) matches a regular expression in `string`.\n",
        "required": [
          "type",
          "string"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "MATCHES_STRING"
            ]
          },
          "negate": {
            "type": "boolean",
            "example": false
          },
          "attribute": {
            "type": "string",
            "example": "email"
          },
          "string": {
            "type": "string",
            "description": "Regular expression.",
            "example": ".*@example.com"
          }
        },
        "example": {
          "type": "MATCHES_STRING",
          "attribute": "email",
          "string": ".*@example.com"
        }
      },
      "SemverCompareMatcher": {
        "type": "object",
        "additionalProperties": false,
        "description": "Attribute compared to a single semantic-version string.",
        "required": [
          "type",
          "attribute",
          "string"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "EQUAL_TO_SEMVER",
              "GREATER_THAN_OR_EQUAL_TO_SEMVER",
              "LESS_THAN_OR_EQUAL_TO_SEMVER"
            ]
          },
          "negate": {
            "type": "boolean",
            "example": false
          },
          "attribute": {
            "type": "string",
            "example": "appVersion"
          },
          "string": {
            "type": "string",
            "example": "1.2.0"
          }
        },
        "example": {
          "type": "GREATER_THAN_OR_EQUAL_TO_SEMVER",
          "attribute": "appVersion",
          "string": "1.2.0"
        }
      },
      "BetweenSemverMatcher": {
        "type": "object",
        "additionalProperties": false,
        "description": "Attribute falls in an inclusive semantic-version range.",
        "required": [
          "type",
          "attribute",
          "betweenString"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "BETWEEN_SEMVER"
            ]
          },
          "negate": {
            "type": "boolean",
            "example": false
          },
          "attribute": {
            "type": "string",
            "example": "appVersion"
          },
          "betweenString": {
            "$ref": "#/components/schemas/BetweenStringAttribute"
          }
        },
        "example": {
          "type": "BETWEEN_SEMVER",
          "attribute": "appVersion",
          "betweenString": {
            "from": "1.0.0",
            "to": "2.0.0"
          }
        }
      },
      "InListSemverMatcher": {
        "type": "object",
        "additionalProperties": false,
        "description": "Attribute semantic version is in the listed versions.",
        "required": [
          "type",
          "attribute",
          "strings"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "IN_LIST_SEMVER"
            ]
          },
          "negate": {
            "type": "boolean",
            "example": false
          },
          "attribute": {
            "type": "string",
            "example": "appVersion"
          },
          "strings": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string"
            },
            "example": [
              "1.0.0",
              "1.1.0"
            ]
          }
        },
        "example": {
          "type": "IN_LIST_SEMVER",
          "attribute": "appVersion",
          "strings": [
            "1.0.0",
            "1.1.0"
          ]
        }
      },
      "BetweenNumberAttribute": {
        "type": "object",
        "description": "Inclusive numeric range for BETWEEN_NUMBER and BETWEEN_DATE matchers. Values are int64 — plain numbers for number matchers, epoch millis for date matchers. String/semver ranges use BetweenStringAttribute.\n",
        "required": [
          "from",
          "to"
        ],
        "properties": {
          "from": {
            "type": "integer",
            "format": "int64"
          },
          "to": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "BetweenStringAttribute": {
        "type": "object",
        "description": "Inclusive string range for semantic-version BETWEEN matchers.",
        "required": [
          "from",
          "to"
        ],
        "properties": {
          "from": {
            "type": "string",
            "example": "1.0.0"
          },
          "to": {
            "type": "string",
            "example": "2.0.0"
          }
        }
      },
      "Depends": {
        "type": "object",
        "description": "Feature flag dependency matcher payload.",
        "required": [
          "splitName",
          "treatments"
        ],
        "properties": {
          "splitName": {
            "type": "string",
            "pattern": "^[A-Za-z][-_A-Za-z0-9]*$",
            "maxLength": 100,
            "description": "Name of the prerequisite feature flag.",
            "example": "billing-experience"
          },
          "treatments": {
            "type": "array",
            "minItems": 1,
            "description": "Treatments accepted from the prerequisite feature flag.",
            "items": {
              "$ref": "#/components/schemas/TreatmentName"
            },
            "example": [
              "on"
            ]
          }
        }
      },
      "Impressions": {
        "type": "object",
        "description": "Traffic/impression freshness data for this Feature Flag Definition.\n",
        "required": [
          "lastImpressionAt"
        ],
        "properties": {
          "lastImpressionAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp of the most recent impression recorded for this definition, or `null` if it\nhas never received traffic.\n",
            "example": "2025-06-15T09:30:00Z"
          }
        }
      },
      "FeatureFlagDefinition": {
        "type": "object",
        "description": "An environment-specific Feature Flag Definition.",
        "required": [
          "id",
          "featureFlag",
          "environment",
          "trafficType",
          "isKilled",
          "treatments",
          "defaultTreatment",
          "baselineTreatment",
          "trafficAllocation",
          "rules",
          "defaultRule",
          "createdAt",
          "impressions"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "System-assigned identifier for this feature flag definition.",
            "example": "c3d4e5f6-a7b8-9012-cdef-123456789012"
          },
          "featureFlag": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NamedReference"
              }
            ],
            "description": "Reference to the parent feature flag metadata."
          },
          "environment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NamedReference"
              }
            ],
            "description": "Reference to the environment this definition is scoped to."
          },
          "trafficType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NamedReference"
              }
            ],
            "description": "Reference to the traffic type used to bucket keys."
          },
          "isKilled": {
            "type": "boolean",
            "readOnly": true,
            "description": "Whether the flag is killed in this environment. While killed, all traffic receives\n`defaultTreatment` regardless of rules. Response-only — use the dedicated kill/restore\nactions to change it.\n",
            "example": false
          },
          "treatments": {
            "type": "array",
            "minItems": 2,
            "description": "The treatments available for this flag in this environment.",
            "items": {
              "$ref": "#/components/schemas/Treatment"
            }
          },
          "defaultTreatment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TreatmentName"
              }
            ],
            "description": "Treatment served when the flag is killed, and to traffic outside `trafficAllocation`.\n",
            "example": "off"
          },
          "baselineTreatment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TreatmentName"
              }
            ],
            "description": "Baseline treatment used as the control group for metrics calculations.",
            "example": "off"
          },
          "trafficAllocation": {
            "type": "integer",
            "format": "int32",
            "minimum": 0,
            "maximum": 100,
            "description": "Percentage of total traffic that participates in this flag's evaluation. Traffic\noutside this allocation receives `defaultTreatment`.\n",
            "example": 100
          },
          "rules": {
            "type": "array",
            "description": "Ordered targeting rules. Empty means all traffic falls through to `defaultRule`.",
            "items": {
              "$ref": "#/components/schemas/Rule"
            }
          },
          "defaultRule": {
            "type": "array",
            "minItems": 1,
            "description": "Distribution applied to in-allocation traffic that matches no targeting rule. Bucket\nsizes must sum to 100.\n",
            "items": {
              "$ref": "#/components/schemas/Distribution"
            }
          },
          "flagSets": {
            "type": "array",
            "description": "Flag sets associated with this definition. Empty means the definition belongs to no\nflag set. Assigned on create/PATCH; echoed on GET.\n",
            "items": {
              "$ref": "#/components/schemas/FlagSetReference"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 timestamp when this definition was created.",
            "example": "2025-06-01T12:00:00Z"
          },
          "impressions": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Impressions"
              }
            ],
            "description": "Traffic/impression freshness data for this definition."
          }
        },
        "example": {
          "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"
          }
        }
      },
      "FeatureFlagDefinitionResponse": {
        "type": "object",
        "description": "Feature Flag Definition entity together with the OPA governance result.",
        "required": [
          "entity",
          "governance"
        ],
        "properties": {
          "entity": {
            "$ref": "#/components/schemas/FeatureFlagDefinition"
          },
          "governance": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GovernanceResult"
              }
            ],
            "description": "OPA governance result for the mutation."
          }
        }
      },
      "FeatureFlagDefinitionListResponse": {
        "type": "object",
        "description": "Paginated list of active Feature Flag Definitions.",
        "required": [
          "data",
          "limit",
          "offset",
          "totalCount"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FeatureFlagDefinition"
            }
          },
          "limit": {
            "type": "integer",
            "description": "The page size used for this response.",
            "example": 100
          },
          "offset": {
            "type": "integer",
            "description": "The number of items skipped before the first result.",
            "example": 0
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of active feature flag definitions matching the query.",
            "example": 8
          }
        }
      },
      "CreateFeatureFlagDefinitionRequest": {
        "type": "object",
        "description": "Request body for creating a Feature Flag Definition for the specified feature flag in the\nspecified environment.\n",
        "required": [
          "treatments",
          "defaultTreatment",
          "defaultRule"
        ],
        "properties": {
          "treatments": {
            "type": "array",
            "minItems": 2,
            "description": "The treatments (variations) for this flag in this environment.\n",
            "items": {
              "$ref": "#/components/schemas/TreatmentInput"
            }
          },
          "defaultTreatment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TreatmentName"
              }
            ],
            "description": "Treatment served when the flag is killed, and to traffic outside `trafficAllocation`.\n",
            "example": "off"
          },
          "baselineTreatment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TreatmentName"
              }
            ],
            "description": "Treatment used as the baseline for metrics calculations. Optional; when omitted the\nserver defaults it to `defaultTreatment`.\n",
            "example": "off"
          },
          "trafficAllocation": {
            "type": "integer",
            "format": "int32",
            "minimum": 0,
            "maximum": 100,
            "default": 100,
            "description": "Percentage of traffic exposed to targeting (traffic allocation). Defaults to 100.",
            "example": 100
          },
          "rules": {
            "type": "array",
            "description": "Ordered targeting rules evaluated before `defaultRule`.",
            "items": {
              "$ref": "#/components/schemas/RuleInput"
            }
          },
          "defaultRule": {
            "type": "array",
            "minItems": 1,
            "description": "Distribution served to in-allocation traffic that matches no targeting rule. Bucket\nsizes must sum to 100. Required on create — callers must supply at least one bucket\n(typically 100% on `defaultTreatment`).\n",
            "items": {
              "$ref": "#/components/schemas/DistributionInput"
            }
          },
          "flagSets": {
            "type": "array",
            "description": "Flag sets to associate with this definition. Optional; omit or `[]` means no\nassociations. Each item is `{id, type}` with `type` = `FLAG_SET`.\n",
            "items": {
              "$ref": "#/components/schemas/FlagSetReference"
            }
          },
          "comment": {
            "type": "string",
            "description": "Optional audit comment recorded with the create.",
            "example": "Initial definition for production"
          },
          "title": {
            "type": "string",
            "description": "Optional audit title recorded with the create.",
            "example": "Create production definition"
          }
        },
        "example": {
          "treatments": [
            {
              "name": "on"
            },
            {
              "name": "off"
            }
          ],
          "defaultTreatment": "off",
          "baselineTreatment": "off",
          "trafficAllocation": 100,
          "rules": [],
          "defaultRule": [
            {
              "treatment": "off",
              "size": 100
            }
          ],
          "flagSets": [
            {
              "id": "d4e5f6a7-b8c9-0123-def0-234567890123"
            }
          ]
        }
      },
      "UpdateFeatureFlagDefinitionRequest": {
        "type": "object",
        "description": "JSON Merge Patch body (RFC 7396). Omit a field to leave it unchanged. Array fields\n(`treatments`, `rules`, `defaultRule`, `flagSets`) are replaced in full when present;\n`null` for those arrays is a validation error (`400`). `flagSets: []` is a full replace\nwith no associations (clears membership). Scalar fields (`defaultTreatment`,\n`baselineTreatment`, `trafficAllocation`, `comment`, `title`) are non-clearable and\nset-only — omitting the field and sending JSON `null` both leave the existing value\nunchanged (`null` is treated the same as omit); there is no invent-clear, and there is no\nway to clear these fields via this endpoint.\n",
        "properties": {
          "treatments": {
            "type": "array",
            "minItems": 2,
            "description": "Full replacement of the treatment list.",
            "items": {
              "$ref": "#/components/schemas/TreatmentInput"
            }
          },
          "defaultTreatment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TreatmentName"
              }
            ],
            "description": "Updated default treatment.",
            "example": "off"
          },
          "baselineTreatment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TreatmentName"
              }
            ],
            "description": "Updated baseline treatment.",
            "example": "off"
          },
          "trafficAllocation": {
            "type": "integer",
            "format": "int32",
            "minimum": 0,
            "maximum": 100,
            "description": "Updated traffic allocation percentage.",
            "example": 100
          },
          "rules": {
            "type": "array",
            "description": "Full replacement of the ordered targeting rules.",
            "items": {
              "$ref": "#/components/schemas/RuleInput"
            }
          },
          "defaultRule": {
            "type": "array",
            "minItems": 1,
            "description": "Full replacement of the default distribution. Empty `[]` and `null` are rejected\n(`400`).\n",
            "items": {
              "$ref": "#/components/schemas/DistributionInput"
            }
          },
          "flagSets": {
            "type": "array",
            "description": "Full replacement of flag-set associations. Omit to leave unchanged. Present array\n(including `[]`) replaces membership; `null` is a validation error (`400`).\n",
            "items": {
              "$ref": "#/components/schemas/FlagSetReference"
            }
          },
          "comment": {
            "type": "string",
            "description": "Optional audit comment recorded with the update.",
            "example": "Ramping to 50% on-treatment"
          },
          "title": {
            "type": "string",
            "description": "Optional audit title recorded with the update.",
            "example": "50% rollout"
          }
        },
        "example": {
          "trafficAllocation": 50
        }
      },
      "FeatureFlagDefinitionActionRequest": {
        "type": "object",
        "description": "Optional metadata supplied when killing, restoring, or reallocating a feature flag definition.",
        "properties": {
          "comment": {
            "type": "string",
            "description": "Optional comment recorded with the action.",
            "example": "Disabling the feature during incident mitigation."
          },
          "title": {
            "type": "string",
            "description": "Optional title recorded with the action.",
            "example": "Kill billing-experience in production"
          }
        }
      },
      "TreatmentName": {
        "type": "string",
        "pattern": "^[a-zA-Z0-9][-_\\.a-zA-Z0-9]*$",
        "description": "Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods.\n",
        "example": "on"
      },
      "FlagSetReference": {
        "type": "object",
        "description": "Flag set associated with a feature flag definition. Used on create, update, and GET.\nIdentify the flag set by `id`. `name` is not accepted or returned.\n",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "System-assigned identifier for the flag set.",
            "example": "d4e5f6a7-b8c9-0123-def0-234567890123"
          }
        },
        "example": {
          "id": "d4e5f6a7-b8c9-0123-def0-234567890123"
        }
      },
      "Segment": {
        "type": "object",
        "description": "A workspace-scoped Segment metadata entity (`STANDARD`, `LARGE`, or `RULE_BASED`).",
        "required": [
          "id",
          "name",
          "trafficType",
          "createdAt",
          "status",
          "tags",
          "owners",
          "segmentType"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique system-assigned identifier for the segment.",
            "example": "c3d4e5f6-a7b8-9012-cdef-123456789012"
          },
          "name": {
            "type": "string",
            "description": "Immutable after creation. Unique among active STANDARD and LARGE names in the project.\nIf rule-based segments are enabled for the account, the name must also be unique\nagainst active RULE_BASED names. Resolve with path `segment-name` plus query\n`segment_type`.\n",
            "example": "power-users"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Human-readable description of this segment.",
            "example": "Users with elevated privileges"
          },
          "trafficType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NamedReference"
              }
            ],
            "description": "Reference to the traffic type used to bucket users."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 timestamp when the segment was created.",
            "example": "2025-06-01T12:00:00Z"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "ARCHIVED"
            ],
            "description": "Lifecycle status of the segment.\n- `ACTIVE` — segment is live.\n- `ARCHIVED` — segment is no longer active (soft-deleted).\n",
            "example": "ACTIVE"
          },
          "tags": {
            "type": "array",
            "description": "Tags associated with this segment.",
            "items": {
              "$ref": "#/components/schemas/NamedReference"
            }
          },
          "owners": {
            "type": "array",
            "description": "Users or teams that own this segment. `USER` owners include `email`; `GROUP` owners do\nnot.\n",
            "items": {
              "$ref": "#/components/schemas/OwnerReference"
            }
          },
          "segmentType": {
            "$ref": "#/components/schemas/SegmentKind"
          }
        },
        "example": {
          "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
          "name": "power-users",
          "description": "Users with elevated privileges",
          "trafficType": {
            "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
            "name": "user"
          },
          "createdAt": "2025-06-01T12:00:00Z",
          "status": "ACTIVE",
          "tags": [
            {
              "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad322",
              "name": "backend"
            }
          ],
          "owners": [
            {
              "id": "xM5qi75eQYmdgJYfwNoHEQ",
              "type": "USER",
              "name": "Alice Example",
              "email": "alice@example.com"
            },
            {
              "id": "VP5X_K9mTqR2nLw8sYcHdA",
              "type": "GROUP",
              "name": "platform-team"
            }
          ],
          "segmentType": "STANDARD"
        }
      },
      "SegmentKind": {
        "type": "string",
        "enum": [
          "STANDARD",
          "LARGE",
          "RULE_BASED"
        ],
        "description": "Kind of segment (`STANDARD`, `LARGE`, or `RULE_BASED`). Distinct from resource `type`\n(`SEGMENT`).\n",
        "example": "STANDARD"
      },
      "SegmentResponse": {
        "type": "object",
        "description": "Mutation response (create, update): entity plus OPA governance.\n",
        "required": [
          "entity",
          "governance"
        ],
        "properties": {
          "entity": {
            "$ref": "#/components/schemas/Segment"
          },
          "governance": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GovernanceResult"
              }
            ],
            "description": "OPA governance result for the mutation."
          }
        }
      },
      "SegmentListResponse": {
        "type": "object",
        "description": "Paginated list of Segments matching the query.",
        "required": [
          "data",
          "limit",
          "offset",
          "totalCount"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Segment"
            }
          },
          "limit": {
            "type": "integer",
            "description": "The page size used for this response.",
            "example": 100
          },
          "offset": {
            "type": "integer",
            "description": "The number of items skipped before the first result.",
            "example": 0
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of segments matching the query.",
            "example": 42
          }
        }
      },
      "CreateSegmentRequest": {
        "type": "object",
        "description": "Request body for creating a Segment. Same fields for every `segmentType`.",
        "required": [
          "name",
          "trafficType",
          "segmentType"
        ],
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^[A-Za-z][-_A-Za-z0-9]*$",
            "maxLength": 100,
            "description": "Unique among active STANDARD and LARGE names in the project. Immutable after creation.\nIf rule-based segments are enabled for the account, the name must also be unique\nagainst active RULE_BASED names.\n",
            "example": "power-users"
          },
          "description": {
            "type": "string",
            "description": "Human-readable description of this segment.",
            "example": "Users with elevated privileges"
          },
          "trafficType": {
            "type": "string",
            "description": "Traffic type used to bucket users, identified by its name (for example `user` or\n`account`). Immutable after creation.\n",
            "example": "user"
          },
          "tags": {
            "type": "array",
            "description": "Initial tags to associate with the segment.",
            "items": {
              "$ref": "#/components/schemas/TagReferenceInput"
            }
          },
          "owners": {
            "type": "array",
            "description": "Initial owners (users or teams) for this segment. If omitted or empty, the project's\ndefault admin team is assigned.\n",
            "items": {
              "$ref": "#/components/schemas/OwnerReferenceInput"
            }
          },
          "segmentType": {
            "$ref": "#/components/schemas/SegmentKind"
          }
        },
        "example": {
          "name": "power-users",
          "description": "Users with elevated privileges",
          "trafficType": "user",
          "segmentType": "STANDARD",
          "tags": [
            {
              "name": "backend"
            }
          ],
          "owners": [
            {
              "type": "USER",
              "email": "alice@example.com"
            }
          ]
        }
      },
      "UpdateSegmentRequest": {
        "type": "object",
        "additionalProperties": false,
        "description": "JSON Merge Patch body (RFC 7396) for updating a Segment. All fields are optional. Omit a\nfield to leave it unchanged; send JSON `null` to clear `description`, or `null`/`[]` to clear\n`tags`/`owners`. Present array fields replace the list in full. Kind is selected by query\n`segment_type`. `segmentType` is not patchable. Unknown properties return `400`.\n",
        "properties": {
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Updated human-readable description.",
            "example": "Updated segment description"
          },
          "tags": {
            "type": "array",
            "nullable": true,
            "description": "Replacement tag list.",
            "items": {
              "$ref": "#/components/schemas/TagReferenceInput"
            }
          },
          "owners": {
            "type": "array",
            "nullable": true,
            "description": "Replacement owner list.",
            "items": {
              "$ref": "#/components/schemas/OwnerReferenceInput"
            }
          }
        },
        "example": {
          "description": "Updated segment description",
          "tags": [
            {
              "name": "backend"
            }
          ],
          "owners": [
            {
              "type": "GROUP",
              "identifier": "platform-team"
            }
          ]
        }
      },
      "SegmentDefinition": {
        "type": "object",
        "description": "An environment-specific Segment Definition (standard segment instance).",
        "required": [
          "id",
          "segment",
          "environment",
          "createdAt",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "System-assigned identifier for this segment definition.",
            "example": "d4e5f6a7-b8c9-0123-def0-234567890123"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Human-readable description of this segment in the given environment.",
            "example": "Power users in production"
          },
          "segment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NamedReference"
              }
            ],
            "description": "Reference to the parent segment metadata."
          },
          "environment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NamedReference"
              }
            ],
            "description": "Reference to the environment this definition is scoped to."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 timestamp when this definition was created.",
            "example": "2025-06-01T12:00:00Z"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "ARCHIVED"
            ],
            "description": "Lifecycle status of the segment definition.\n- `ACTIVE` — definition is live.\n- `ARCHIVED` — definition is no longer active (soft-deleted).\n",
            "example": "ACTIVE"
          }
        },
        "example": {
          "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
          "description": "Power users in production",
          "segment": {
            "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
            "name": "power-users"
          },
          "environment": {
            "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
            "name": "Production"
          },
          "createdAt": "2025-06-01T12:00:00Z",
          "status": "ACTIVE"
        }
      },
      "SegmentDefinitionResponse": {
        "type": "object",
        "description": "Mutation response (create, update): entity plus OPA governance.\n",
        "required": [
          "entity",
          "governance"
        ],
        "properties": {
          "entity": {
            "$ref": "#/components/schemas/SegmentDefinition"
          },
          "governance": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GovernanceResult"
              }
            ],
            "description": "OPA governance result for the mutation."
          }
        }
      },
      "SegmentDefinitionListResponse": {
        "type": "object",
        "description": "Paginated list of Segment Definitions matching the query.",
        "required": [
          "data",
          "limit",
          "offset",
          "totalCount"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SegmentDefinition"
            }
          },
          "limit": {
            "type": "integer",
            "description": "The page size used for this response.",
            "example": 100
          },
          "offset": {
            "type": "integer",
            "description": "The number of items skipped before the first result.",
            "example": 0
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of segment definitions matching the query.",
            "example": 8
          }
        }
      },
      "CreateSegmentDefinitionRequest": {
        "type": "object",
        "description": "Optional body. Omit or send `{}` to create the default definition shell.",
        "properties": {
          "description": {
            "type": "string",
            "description": "Human-readable description of this segment in the given environment.",
            "example": "Power users in production"
          }
        },
        "example": {
          "description": "Power users in production"
        }
      },
      "UpdateSegmentDefinitionRequest": {
        "type": "object",
        "description": "JSON Merge Patch body (RFC 7396) for updating a Segment Definition. Only `description` is\nupdatable. Omit the field to leave it unchanged; send JSON `null` to clear it.\n",
        "properties": {
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Updated description, or `null` to clear.",
            "example": "Updated production power users"
          }
        },
        "example": {
          "description": "Updated production power users"
        }
      },
      "SegmentDefinitionKeysAddRequest": {
        "type": "object",
        "description": "Request body for adding membership keys (or replacing membership when `replace=true`).\nAn empty `keys` array is allowed and clears membership when `replace=true`; when\n`replace=false`, the server rejects an empty list.\n",
        "required": [
          "keys"
        ],
        "properties": {
          "keys": {
            "type": "array",
            "description": "Traffic keys (for example, user identifiers) to add or replace with.",
            "maxItems": 10000,
            "items": {
              "type": "string",
              "minLength": 1
            },
            "example": [
              "user-1001",
              "user-1002"
            ]
          },
          "comment": {
            "type": "string",
            "description": "Optional comment recorded with the action.",
            "example": "Onboarding cohort for Q3 rollout"
          },
          "title": {
            "type": "string",
            "description": "Optional title recorded with the action.",
            "example": "Add power-user cohort"
          }
        }
      },
      "SegmentDefinitionKeysRemoveRequest": {
        "type": "object",
        "description": "Request body for removing membership keys from a Segment Definition.",
        "required": [
          "keys"
        ],
        "properties": {
          "keys": {
            "type": "array",
            "description": "Traffic keys (for example, user identifiers) to remove.",
            "minItems": 1,
            "maxItems": 10000,
            "items": {
              "type": "string",
              "minLength": 1
            },
            "example": [
              "user-1001",
              "user-1002"
            ]
          },
          "comment": {
            "type": "string",
            "description": "Optional comment recorded with the action.",
            "example": "Remove churned cohort"
          },
          "title": {
            "type": "string",
            "description": "Optional title recorded with the action.",
            "example": "Remove churned users"
          }
        }
      },
      "SegmentDefinitionKeyListResponse": {
        "type": "object",
        "description": "Paginated list of membership keys for a Segment Definition.",
        "required": [
          "data",
          "limit",
          "offset",
          "totalCount"
        ],
        "properties": {
          "data": {
            "type": "array",
            "description": "Membership keys on this page.",
            "items": {
              "type": "string"
            },
            "example": [
              "user-1001",
              "user-1002"
            ]
          },
          "limit": {
            "type": "integer",
            "description": "The page size used for this response.",
            "example": 100
          },
          "offset": {
            "type": "integer",
            "description": "The number of items skipped before the first result.",
            "example": 0
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of membership keys in the Segment Definition.",
            "example": 250
          }
        }
      },
      "SegmentDefinitionKeysMutationResponse": {
        "type": "object",
        "description": "Submitted membership keys together with the OPA governance result.",
        "required": [
          "keys",
          "governance"
        ],
        "properties": {
          "keys": {
            "type": "array",
            "description": "Submitted keys accepted for processing. May include keys that were already members\n(add) or keys that were not members (remove); those cases are treated as no-ops.\n",
            "items": {
              "type": "string"
            },
            "example": [
              "user-1001",
              "user-1002"
            ]
          },
          "governance": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GovernanceResult"
              }
            ],
            "description": "OPA governance result for the mutation."
          }
        }
      },
      "Environment": {
        "type": "object",
        "description": "A workspace-scoped Environment entity.",
        "required": [
          "id",
          "name",
          "isProduction",
          "createdAt",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique system-assigned identifier for the environment.",
            "example": "ad2eb8f0-9c3a-11ed-873c-e234abaad319"
          },
          "name": {
            "type": "string",
            "description": "Unique environment name within the project. Updatable via PATCH. Use the system-assigned\n`id` as the path parameter in subsequent requests — this field is informational only.\n",
            "example": "Production"
          },
          "isProduction": {
            "type": "boolean",
            "description": "`true` when this environment represents production traffic. Defaults to `false` when\nomitted at creation time.\n",
            "example": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 timestamp when the environment was created.",
            "example": "2025-06-01T12:00:00Z"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "ARCHIVED"
            ],
            "description": "Lifecycle status of the environment.\n- `ACTIVE` — environment is live.\n- `ARCHIVED` — environment is no longer active (soft-deleted).\n",
            "example": "ACTIVE"
          }
        },
        "example": {
          "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
          "name": "Production",
          "isProduction": true,
          "createdAt": "2025-06-01T12:00:00Z",
          "status": "ACTIVE"
        }
      },
      "EnvironmentResponse": {
        "type": "object",
        "description": "Mutation response (create, update): entity plus OPA governance.\n",
        "required": [
          "entity",
          "governance"
        ],
        "properties": {
          "entity": {
            "$ref": "#/components/schemas/Environment"
          },
          "governance": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GovernanceResult"
              }
            ],
            "description": "OPA governance result for the mutation."
          }
        }
      },
      "EnvironmentListResponse": {
        "type": "object",
        "description": "Paginated list of Environments matching the query.",
        "required": [
          "data",
          "limit",
          "offset",
          "totalCount"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Environment"
            }
          },
          "limit": {
            "type": "integer",
            "description": "The page size used for this response.",
            "example": 100
          },
          "offset": {
            "type": "integer",
            "description": "The number of items skipped before the first result.",
            "example": 0
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of environments matching the query.",
            "example": 5
          }
        }
      },
      "CreateEnvironmentRequest": {
        "type": "object",
        "description": "Request body for creating a new Environment.",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Unique environment name within the project.",
            "example": "Production"
          },
          "isProduction": {
            "type": "boolean",
            "description": "`true` when this environment represents production traffic. Defaults to `false` when\nomitted.\n",
            "default": false,
            "example": true
          }
        },
        "example": {
          "name": "Production",
          "isProduction": true
        }
      },
      "UpdateEnvironmentRequest": {
        "type": "object",
        "description": "JSON Merge Patch body (RFC 7396). All fields are optional. Omit a field to leave it\nunchanged. Sending `null` for `name` or `isProduction`, or a blank `name`, is rejected\nwith `400`.\n",
        "properties": {
          "name": {
            "type": "string",
            "description": "Updated environment name.",
            "example": "Production-US"
          },
          "isProduction": {
            "type": "boolean",
            "description": "Updated production flag.",
            "example": true
          }
        },
        "example": {
          "name": "Production-US",
          "isProduction": true
        }
      },
      "TrafficType": {
        "type": "object",
        "description": "A workspace-scoped Traffic Type.",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique system-assigned identifier for the traffic type.",
            "example": "ad2eb8f0-9c3a-11ed-873c-e234abaad323"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 50,
            "pattern": "^[a-z][a-z0-9\\-_]*$",
            "description": "Unique traffic type name within the project. Must begin with a lowercase letter and\nmay contain lowercase letters, numbers, hyphens, and underscores. Use this value as\n`trafficType` when creating feature flags, segments, or metrics.\n",
            "example": "user"
          }
        },
        "example": {
          "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
          "name": "user"
        }
      },
      "TrafficTypeListResponse": {
        "type": "object",
        "description": "Paginated list of Traffic Types matching the query.",
        "required": [
          "data",
          "limit",
          "offset",
          "totalCount"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TrafficType"
            }
          },
          "limit": {
            "type": "integer",
            "description": "The page size used for this response.",
            "example": 100
          },
          "offset": {
            "type": "integer",
            "description": "The number of items skipped before the first result.",
            "example": 0
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of traffic types matching the query.",
            "example": 2
          }
        }
      },
      "EventType": {
        "type": "object",
        "description": "A project-scoped Event Type. Event types are read-only: they are observed by the events\ningestion pipeline rather than created through this API, which is also why they carry no\ndisplay name or description — the pipeline records neither.\n",
        "required": [
          "id",
          "trafficTypes"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The event name assigned by the ingestion pipeline (the value sent as `eventTypeId` by\nSDKs) — not a system-generated UUID. Use this value as `baseEventTypes[].eventTypeId`\nor `filterEventType.eventTypeId` when creating a metric.\n",
            "example": "purchase"
          },
          "trafficTypes": {
            "type": "array",
            "description": "Traffic types this event type is associated with, restricted to those also in scope\nfor the requesting workspace.\n",
            "items": {
              "$ref": "#/components/schemas/NamedReferenceObject"
            }
          }
        },
        "example": {
          "id": "purchase",
          "trafficTypes": [
            {
              "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
              "name": "user"
            }
          ]
        }
      },
      "EventTypeListResponse": {
        "type": "object",
        "required": [
          "data",
          "limit",
          "offset",
          "totalCount"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EventType"
            }
          },
          "limit": {
            "type": "integer",
            "example": 100
          },
          "offset": {
            "type": "integer",
            "example": 0
          },
          "totalCount": {
            "type": "integer",
            "format": "int64",
            "example": 2
          }
        }
      },
      "NamedReferenceObject": {
        "type": "object",
        "description": "Reference to another resource whose kind is already implied by the parent field (for\nexample `trafficTypes`, `tags`, `environment`), so no `type` discriminator is returned.\nUse `ReferenceObject` where the kind is ambiguous (owners: `USER` vs `GROUP`).\n",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the referenced resource.",
            "example": "ad2eb8f0-9c3a-11ed-873c-e234abaad323"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name of the referenced resource.",
            "example": "user"
          }
        },
        "example": {
          "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
          "name": "user"
        }
      },
      "ExperimentName": {
        "type": "string",
        "minLength": 2,
        "maxLength": 250,
        "pattern": "^[a-zA-Z][-_a-zA-Z0-9]+$",
        "description": "Unique experiment name within the project.",
        "example": "checkout-experiment"
      },
      "ExperimentStatus": {
        "type": "string",
        "enum": [
          "ACTIVE",
          "PAUSED",
          "ARCHIVED",
          "COMPLETED"
        ],
        "description": "Experiment lifecycle status. New experiments are `ACTIVE`. `PATCH` can set `PAUSED`,\n`ARCHIVED`, or `COMPLETED`. `DELETE` removes the experiment permanently rather than\nsetting `status: ARCHIVED` (see the delete endpoint).\n"
      },
      "ExperimentParentType": {
        "type": "string",
        "enum": [
          "FEATURE_FLAG",
          "AI_CONFIG",
          "CONFIG"
        ],
        "description": "Kind of parent the experiment runs on. `CONFIG` and `AI_CONFIG` are separate types.\nWarehouse-native experiments are not a parent type; they use `assignmentSource` on\nthis same resource when implemented.\n"
      },
      "ExperimentParent": {
        "type": "object",
        "additionalProperties": false,
        "description": "Parent Feature Flag, AI Config, or Config (id and name).",
        "required": [
          "type",
          "id",
          "name"
        ],
        "properties": {
          "type": {
            "$ref": "#/components/schemas/ExperimentParentType"
          },
          "id": {
            "type": "string",
            "description": "System-assigned identifier of the parent. Feature Flag ids are UUIDs; Config and\nAI Config ids are the AppConfig metadata id.\n"
          },
          "name": {
            "type": "string",
            "description": "Human-readable parent name.",
            "pattern": "^[A-Za-z][-_A-Za-z0-9]*$",
            "maxLength": 100
          }
        }
      },
      "ExperimentParentReference": {
        "type": "object",
        "additionalProperties": false,
        "description": "Parent to run the experiment on. `type` is required. Supply `id` and/or `name`.\n",
        "required": [
          "type"
        ],
        "anyOf": [
          {
            "required": [
              "id"
            ]
          },
          {
            "required": [
              "name"
            ]
          }
        ],
        "properties": {
          "type": {
            "$ref": "#/components/schemas/ExperimentParentType"
          },
          "id": {
            "type": "string",
            "description": "Parent id. At least one of `id` or `name` is required."
          },
          "name": {
            "type": "string",
            "description": "Parent name. At least one of `id` or `name` is required.",
            "pattern": "^[A-Za-z][-_A-Za-z0-9]*$",
            "maxLength": 100,
            "example": "checkout-flag"
          }
        }
      },
      "ExperimentOwnerReference": {
        "type": "object",
        "additionalProperties": false,
        "description": "Reference to an owner (user or team) of an experiment.",
        "required": [
          "type",
          "id"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "USER",
              "TEAM"
            ],
            "description": "Owner kind.",
            "example": "USER"
          },
          "id": {
            "type": "string",
            "description": "Identifier of the owner — the Harness user id (for `USER`) or team id (for `TEAM`).",
            "example": "xM5qi75eQYmdgJYfwNoHEQ"
          }
        },
        "example": {
          "type": "USER",
          "id": "xM5qi75eQYmdgJYfwNoHEQ"
        }
      },
      "AssignmentSourceReference": {
        "type": "object",
        "additionalProperties": false,
        "description": "Impression assignment source (`type` is `ASSIGNMENT_SOURCE`).",
        "required": [
          "type",
          "id"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "ASSIGNMENT_SOURCE"
            ],
            "description": "Resource type. Always `ASSIGNMENT_SOURCE`."
          },
          "id": {
            "type": "string",
            "format": "ulid",
            "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
            "description": "System-assigned identifier of the assignment source."
          }
        }
      },
      "Experiment": {
        "type": "object",
        "additionalProperties": false,
        "description": "A workspace-scoped Experiment.",
        "required": [
          "type",
          "id",
          "name",
          "environment",
          "trafficType",
          "startAt",
          "endAt",
          "baselineTreatment",
          "comparisonTreatments",
          "keyMetrics",
          "supportingMetrics",
          "tags",
          "owners",
          "status",
          "createdAt",
          "modifiedAt"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "EXPERIMENT"
            ],
            "description": "Resource type discriminator. Always `EXPERIMENT`."
          },
          "id": {
            "type": "string",
            "format": "ulid",
            "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
            "description": "Unique system-assigned identifier for the experiment. Use this as the path parameter in subsequent requests.",
            "example": "01JAFXNTQHH8QTPTWYSG8H04Y5"
          },
          "parent": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ExperimentParent"
              }
            ],
            "description": "Present for Feature Flag, AI Config, and Config. Omitted for warehouse-native\nexperiments when that revision ships (those use `assignmentSource` instead).\nA given experiment returns exactly one of `parent` or `assignmentSource`, never both.\nThis revision always returns `parent` and omits `assignmentSource`.\n"
          },
          "assignmentSource": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AssignmentSourceReference"
              }
            ],
            "description": "Omitted for Feature Flag, AI Config, and Config. Present when warehouse-native\nexperiments are implemented. Mutually exclusive with `parent` (see `parent`).\nNot returned in this revision.\n"
          },
          "name": {
            "type": "string",
            "minLength": 2,
            "maxLength": 250,
            "pattern": "^[a-zA-Z][-_a-zA-Z0-9]+$",
            "description": "Unique experiment name within the project.",
            "example": "checkout-experiment"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "maxLength": 250,
            "description": "Human-readable description of this experiment."
          },
          "hypothesis": {
            "type": "string",
            "nullable": true,
            "maxLength": 500,
            "description": "Hypothesis this experiment is testing."
          },
          "environment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NamedReference"
              }
            ],
            "description": "Environment this experiment is assigned in."
          },
          "trafficType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NamedReference"
              }
            ],
            "description": "Reference to the traffic type used to bucket users."
          },
          "startAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 timestamp when the experiment starts.",
            "example": "2025-06-01T12:00:00Z"
          },
          "endAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 timestamp when the experiment ends.",
            "example": "2025-07-01T12:00:00Z"
          },
          "baselineTreatment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TreatmentName"
              }
            ],
            "description": "Baseline treatment name."
          },
          "comparisonTreatments": {
            "type": "array",
            "minItems": 1,
            "description": "Comparison treatments (not including `baselineTreatment`).",
            "items": {
              "$ref": "#/components/schemas/TreatmentName"
            }
          },
          "keyMetrics": {
            "type": "array",
            "description": "Key metrics on this experiment.",
            "items": {
              "$ref": "#/components/schemas/NamedReference"
            }
          },
          "supportingMetrics": {
            "type": "array",
            "description": "Supporting metrics on this experiment.",
            "items": {
              "$ref": "#/components/schemas/NamedReference"
            }
          },
          "tags": {
            "type": "array",
            "description": "Tags associated with this experiment (each `type` is `TAG`).",
            "items": {
              "$ref": "#/components/schemas/ReferenceObject"
            }
          },
          "owners": {
            "type": "array",
            "description": "Users or teams that own this experiment. Empty if none were set on create.",
            "items": {
              "$ref": "#/components/schemas/ExperimentOwnerReference"
            }
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ExperimentStatus"
              }
            ],
            "description": "Lifecycle status of the experiment. Get returns the experiment regardless of status (`ACTIVE`, `PAUSED`, `ARCHIVED`, or `COMPLETED`)."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 timestamp when the experiment was created.",
            "example": "2025-06-01T12:00:00Z"
          },
          "modifiedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 timestamp when the experiment was last modified.",
            "example": "2025-06-15T09:30:00Z"
          },
          "rule": {
            "type": "string",
            "nullable": true,
            "description": "Targeting-rule label this experiment's results are scoped to (e.g. `\"default rule\"` or\na specific targeting rule name on the parent flag). `null` when the experiment was\ncreated without one, in which case results use the experiment's default rule scope.\n",
            "example": "default rule"
          }
        },
        "example": {
          "type": "EXPERIMENT",
          "id": "01JAFXNTQHH8QTPTWYSG8H04Y5",
          "parent": {
            "type": "FEATURE_FLAG",
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "name": "checkout-flag"
          },
          "name": "checkout-experiment",
          "description": null,
          "hypothesis": "Checkout conversion increases with treatment on.",
          "environment": {
            "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad319",
            "name": "Production"
          },
          "trafficType": {
            "id": "a707c5af-94c1-4ca1-99dc-f0e72981c9ec",
            "name": "user"
          },
          "startAt": "2025-06-01T12:00:00Z",
          "endAt": "2025-07-01T12:00:00Z",
          "baselineTreatment": "off",
          "comparisonTreatments": [
            "on"
          ],
          "keyMetrics": [
            {
              "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567892",
              "name": "conversion"
            }
          ],
          "supportingMetrics": [],
          "tags": [
            {
              "id": "checkout",
              "type": "TAG",
              "name": "checkout"
            }
          ],
          "owners": [
            {
              "type": "USER",
              "id": "xM5qi75eQYmdgJYfwNoHEQ"
            }
          ],
          "status": "ACTIVE",
          "createdAt": "2025-06-01T12:00:00Z",
          "modifiedAt": "2025-06-15T09:30:00Z",
          "rule": "default rule"
        }
      },
      "ExperimentResponse": {
        "type": "object",
        "description": "Experiment mutation response envelope. Returned by create and update: the resulting entity\ntogether with the OPA governance result. Experiments are not a governed entity type, so\n`governance` is always present with `status: NONE` and empty `details` (no policy\nevaluation occurs); the envelope is kept for response-shape consistency with other v4\nresources.\n",
        "required": [
          "entity",
          "governance"
        ],
        "properties": {
          "entity": {
            "$ref": "#/components/schemas/Experiment"
          },
          "governance": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GovernanceResult"
              }
            ],
            "description": "OPA governance result for the mutation. For experiments this is always `{ \"status\": \"NONE\",\n\"details\": [] }` — `EXPERIMENT` is not a governed entity type, so no policy evaluation\noccurs. Present (never `null`) for response-shape consistency with other v4 resources.\n"
          }
        }
      },
      "ExperimentListResponse": {
        "type": "object",
        "description": "Paginated list of Experiments matching the query.",
        "required": [
          "data",
          "limit",
          "offset",
          "totalCount"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Experiment"
            }
          },
          "limit": {
            "type": "integer",
            "description": "The page size used for this response.",
            "example": 100
          },
          "offset": {
            "type": "integer",
            "description": "The number of items skipped before the first result.",
            "example": 0
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of experiments matching the query.",
            "example": 42
          }
        }
      },
      "CreateExperimentRequest": {
        "type": "object",
        "additionalProperties": false,
        "description": "Request body for creating a new Experiment. `parent.type` plus `parent.id` and/or\n`parent.name` are required. Do not send `assignmentSource` (`400` if present).\n",
        "required": [
          "parent",
          "name",
          "startAt",
          "endAt",
          "baselineTreatment",
          "comparisonTreatments"
        ],
        "properties": {
          "parent": {
            "$ref": "#/components/schemas/ExperimentParentReference"
          },
          "name": {
            "$ref": "#/components/schemas/ExperimentName"
          },
          "description": {
            "type": "string",
            "maxLength": 250,
            "description": "Human-readable description of this experiment."
          },
          "hypothesis": {
            "type": "string",
            "maxLength": 500,
            "description": "Hypothesis this experiment is testing."
          },
          "rule": {
            "type": "string",
            "description": "Targeting-rule label to scope this experiment's results to (e.g. `\"default rule\"` or a\nspecific targeting rule name on the parent flag). Omit to use the experiment's default\nrule scope.\n",
            "example": "default rule"
          },
          "startAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 timestamp when the experiment starts.",
            "example": "2025-06-01T12:00:00Z"
          },
          "endAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 timestamp when the experiment ends.",
            "example": "2025-07-01T12:00:00Z"
          },
          "baselineTreatment": {
            "$ref": "#/components/schemas/TreatmentName"
          },
          "comparisonTreatments": {
            "type": "array",
            "minItems": 1,
            "description": "Comparison treatments (not including `baselineTreatment`).",
            "items": {
              "$ref": "#/components/schemas/TreatmentName"
            }
          },
          "keyMetrics": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Metric ids to set as key metrics. Omit for none.",
            "example": [
              "a1b2c3d4-e5f6-7890-abcd-ef1234567892"
            ]
          },
          "supportingMetrics": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Metric ids to set as supporting metrics. Omit for none.",
            "example": []
          },
          "tags": {
            "type": "array",
            "description": "Initial tags to associate with the experiment. Uses the shared `TagReferenceInput`\n(`{ name }`); tags are returned as full `{ type, id, name }` refs on read.\n",
            "items": {
              "$ref": "#/components/schemas/TagReferenceInput"
            }
          },
          "owners": {
            "type": "array",
            "description": "Users or teams that own this experiment. Omit for none.",
            "items": {
              "$ref": "#/components/schemas/ExperimentOwnerReference"
            }
          }
        },
        "example": {
          "parent": {
            "type": "FEATURE_FLAG",
            "name": "checkout-flag"
          },
          "name": "checkout-experiment",
          "hypothesis": "Checkout conversion increases with treatment on.",
          "startAt": "2025-06-01T12:00:00Z",
          "endAt": "2025-07-01T12:00:00Z",
          "baselineTreatment": "off",
          "comparisonTreatments": [
            "on"
          ],
          "keyMetrics": [
            "a1b2c3d4-e5f6-7890-abcd-ef1234567892"
          ],
          "tags": [
            {
              "name": "checkout"
            }
          ],
          "owners": [
            {
              "type": "USER",
              "id": "xM5qi75eQYmdgJYfwNoHEQ"
            }
          ]
        }
      },
      "UpdateExperimentRequest": {
        "type": "object",
        "additionalProperties": false,
        "description": "JSON Merge Patch body (RFC 7396) for updating an Experiment. All fields are optional.\nOmit a field to leave it unchanged. JSON `null` (or `[]` for arrays) clears\n`description`, `hypothesis`, `rule`, `keyMetrics`, `supportingMetrics`, `tags`, and `owners`. `name`,\n`startAt`, `endAt`, `baselineTreatment`, `comparisonTreatments`, and `status` cannot be\ncleared: omit to keep; JSON `null` (or `[]` for `comparisonTreatments`) returns `400`.\nParent and environment cannot be changed.\n",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 2,
            "maxLength": 250,
            "pattern": "^[a-zA-Z][-_a-zA-Z0-9]+$",
            "description": "Updated name. `null` is not allowed.",
            "example": "checkout-experiment"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "maxLength": 250,
            "description": "Updated description. `null` clears it."
          },
          "hypothesis": {
            "type": "string",
            "nullable": true,
            "maxLength": 500,
            "description": "Updated hypothesis. `null` clears it."
          },
          "rule": {
            "type": "string",
            "nullable": true,
            "description": "Updated targeting-rule label. `null` clears it, reverting to the experiment's default\nrule scope.\n",
            "example": "default rule"
          },
          "startAt": {
            "type": "string",
            "format": "date-time",
            "description": "Updated start time. `null` is not allowed.",
            "example": "2025-06-02T12:00:00Z"
          },
          "endAt": {
            "type": "string",
            "format": "date-time",
            "description": "Updated end time. `null` is not allowed.",
            "example": "2025-08-01T12:00:00Z"
          },
          "baselineTreatment": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TreatmentName"
              }
            ],
            "description": "Updated baseline treatment. Omit to keep; JSON `null` returns `400`."
          },
          "comparisonTreatments": {
            "type": "array",
            "minItems": 1,
            "description": "Replacement comparison treatments (full replacement; not including `baselineTreatment`).\nAt least one. `null` or `[]` returns `400`.\n",
            "items": {
              "$ref": "#/components/schemas/TreatmentName"
            }
          },
          "keyMetrics": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Replacement key metric ids. `null` or `[]` clears the list."
          },
          "supportingMetrics": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Replacement supporting metric ids. `null` or `[]` clears the list."
          },
          "tags": {
            "type": "array",
            "nullable": true,
            "description": "Replacement tag list (full replacement), using the shared `TagReferenceInput` (`{ name }`).\n`null` or `[]` clears all tags. Tags are returned as full `{ type, id, name }` refs on read.\n",
            "items": {
              "$ref": "#/components/schemas/TagReferenceInput"
            }
          },
          "owners": {
            "type": "array",
            "nullable": true,
            "description": "Replacement owner list (full replacement; not incremental). `null` or `[]` clears all\nowners. Omit to leave unchanged.\n",
            "items": {
              "$ref": "#/components/schemas/ExperimentOwnerReference"
            }
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ExperimentStatus"
              }
            ],
            "description": "Updated lifecycle status. Omit to keep; JSON `null` returns `400`. `ARCHIVED` is a\nstatus on this resource; it is not a substitute for `DELETE`.\n"
          }
        },
        "example": {
          "name": "checkout-experiment-v2",
          "endAt": "2025-08-01T12:00:00Z",
          "status": "PAUSED"
        }
      },
      "ReferenceObject": {
        "type": "object",
        "description": "Generic reference to another resource, returned in responses. `id` is the stable\npublic identifier, `type` disambiguates the referenced entity kind, and `name` is the\nhuman-readable label.\n",
        "required": [
          "id",
          "type",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the referenced resource.",
            "example": "ad2eb8f0-9c3a-11ed-873c-e234abaad322"
          },
          "type": {
            "type": "string",
            "description": "The kind of entity this reference points to (for example `TRAFFIC_TYPE`, `TAG`,\n`USER`, `GROUP`, `ROLLOUT_STATUS`, `FEATURE_FLAG`, `ENVIRONMENT`, or `SEGMENT`).\nEach resource API returns only the kinds relevant to that API.\n",
            "example": "TAG"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name of the referenced resource.",
            "example": "backend"
          }
        },
        "example": {
          "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad322",
          "type": "TAG",
          "name": "backend"
        }
      },
      "Metric": {
        "type": "object",
        "description": "A project-scoped Metric definition, returned by GET, LIST, and inside the mutation\nenvelope. Some fields are read-only (`metricSourceId`, `customFieldFilters`).\n",
        "required": [
          "type",
          "id",
          "name",
          "trafficType",
          "format",
          "aggregation",
          "isPositive",
          "createdAt",
          "status",
          "baseEventTypes",
          "tags",
          "owners"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "METRIC"
            ],
            "description": "Resource type discriminator. Always `METRIC`."
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique system-assigned identifier for the metric. Use this as the path parameter in subsequent requests."
          },
          "name": {
            "type": "string",
            "description": "Unique metric name within the project.",
            "example": "checkout-conversion"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Human-readable description of this metric.",
            "example": "Conversion rate for the new checkout flow"
          },
          "trafficType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ReferenceObject"
              }
            ],
            "description": "Reference to the traffic type this metric measures (`type` is `TRAFFIC_TYPE`)."
          },
          "format": {
            "type": "string",
            "enum": [
              "NUMBER",
              "DOLLAR",
              "PERCENTAGE",
              "SECONDS",
              "MILLISECONDS",
              "BYTES"
            ],
            "description": "Display/measurement format of the metric value."
          },
          "aggregation": {
            "type": "string",
            "enum": [
              "TOTAL",
              "COUNT",
              "RATE",
              "AVERAGE",
              "NONE"
            ],
            "description": "How individual event values are aggregated per unit."
          },
          "isPositive": {
            "type": "boolean",
            "description": "`true` when an increase in this metric is a good outcome."
          },
          "spread": {
            "type": "string",
            "enum": [
              "PER",
              "ACROSS"
            ],
            "description": "Whether the metric is computed per-unit or across the population. Always present on read."
          },
          "baseEventTypes": {
            "type": "array",
            "description": "The base event type(s) this metric measures. At least one.",
            "items": {
              "$ref": "#/components/schemas/BaseEventType"
            }
          },
          "filterEventType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/FilterEventType"
              }
            ],
            "type": "object",
            "nullable": true,
            "description": "Optional filter/trigger event that scopes which units are counted."
          },
          "triggerEventType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TriggerEventType"
              }
            ],
            "type": "object",
            "nullable": true,
            "description": "Optional trigger event (HAS_DONE_BEFORE): the unit must have done this event before the\nbase event for it to be counted.\n"
          },
          "tags": {
            "type": "array",
            "description": "Tags associated with this metric (each `type` is `TAG`).",
            "items": {
              "$ref": "#/components/schemas/ReferenceObject"
            }
          },
          "owners": {
            "type": "array",
            "description": "Users or groups that own this metric. `USER` owners include `email`; `GROUP` owners do not.",
            "items": {
              "$ref": "#/components/schemas/OwnerReference"
            }
          },
          "metricSourceId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "readOnly": true,
            "description": "Warehouse-native metric source this metric reads from, when applicable."
          },
          "customFieldFilters": {
            "type": "object",
            "nullable": true,
            "readOnly": true,
            "description": "Warehouse-native custom-field filters."
          },
          "cap": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MetricCap"
              }
            ],
            "type": "object",
            "nullable": true,
            "description": "Outlier/cap configuration. `null` (or all-zero fields) means no cap is applied."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 timestamp when the metric was created.",
            "example": "2025-06-01T12:00:00Z"
          },
          "modifiedAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 timestamp when the metric was last modified.",
            "example": "2025-06-02T09:30:00Z"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "ARCHIVED"
            ],
            "description": "Lifecycle status of the metric. New metrics are always `ACTIVE`, and `DELETE` removes a\nmetric permanently rather than changing its status (see the delete endpoint). `ARCHIVED`\nis a legacy value that may still appear on metrics created before archiving was replaced\nby hard delete; this API never transitions a metric to `ARCHIVED`.\n"
          }
        },
        "example": {
          "type": "METRIC",
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "name": "checkout-conversion",
          "description": "Conversion rate for the new checkout flow",
          "trafficType": {
            "id": "ad2eb8f0-9c3a-11ed-873c-e234abaad323",
            "type": "TRAFFIC_TYPE",
            "name": "user"
          },
          "format": "PERCENTAGE",
          "aggregation": "COUNT",
          "isPositive": true,
          "spread": "PER",
          "baseEventTypes": [
            {
              "eventTypeId": "checkout_completed",
              "propertyFilters": [],
              "propertyForValue": null
            }
          ],
          "filterEventType": null,
          "triggerEventType": null,
          "tags": [
            {
              "id": "checkout",
              "type": "TAG",
              "name": "checkout"
            }
          ],
          "owners": [
            {
              "id": "user-1",
              "type": "USER",
              "name": "Alice Example",
              "email": "alice@example.com"
            }
          ],
          "metricSourceId": null,
          "customFieldFilters": null,
          "cap": null,
          "createdAt": "2025-06-01T12:00:00Z",
          "modifiedAt": "2025-06-02T09:30:00Z",
          "status": "ACTIVE"
        }
      },
      "BaseEventType": {
        "type": "object",
        "description": "A base event type the metric measures, with optional per-event property filters.",
        "required": [
          "eventTypeId"
        ],
        "properties": {
          "eventTypeId": {
            "type": "string",
            "description": "Identifier of the event type.",
            "example": "checkout_completed"
          },
          "propertyFilters": {
            "type": "array",
            "description": "Optional property filters applied to this base event.",
            "items": {
              "$ref": "#/components/schemas/EventPropertyFilter"
            }
          },
          "propertyForValue": {
            "type": "string",
            "nullable": true,
            "description": "Event property whose value is measured (for value-based aggregations).",
            "example": "amount"
          }
        }
      },
      "FilterEventType": {
        "type": "object",
        "description": "A filter/trigger event that scopes which units the metric counts.",
        "required": [
          "eventTypeId"
        ],
        "properties": {
          "eventTypeId": {
            "type": "string",
            "description": "Identifier of the filter/trigger event type.",
            "example": "session_started"
          },
          "filterAggregation": {
            "type": "string",
            "enum": [
              "TOTAL",
              "COUNT",
              "RATE",
              "AVERAGE",
              "NONE"
            ],
            "nullable": true,
            "description": "Aggregation applied to the filter event."
          },
          "propertyFilters": {
            "type": "array",
            "description": "Optional property filters applied to the filter event.",
            "items": {
              "$ref": "#/components/schemas/EventPropertyFilter"
            }
          }
        }
      },
      "TriggerEventType": {
        "type": "object",
        "description": "A trigger event (HAS_DONE_BEFORE): the unit must have done this event before the base event.\nUnlike `FilterEventType`, a trigger event has no aggregation or property filters.\n",
        "required": [
          "eventTypeId"
        ],
        "properties": {
          "eventTypeId": {
            "type": "string",
            "description": "Identifier of the trigger event type.",
            "example": "account_created"
          }
        }
      },
      "EventPropertyFilter": {
        "type": "object",
        "description": "A filter on an event property. The operand field must match the `operator` (validated\nserver-side; a mismatch is rejected with `400`, `errorType: operatorOperandMismatch`):\n- scalar operators (`EQUAL`, `GREATER_THAN`, `LESS_THAN`, `STRING_EQUAL`, `CONTAINS`,\n  `STARTS_WITH`, `BOOLEAN_EQUAL`) use `secondOperand`;\n- `STRING_IN_LIST` uses `stringInListOperand` (non-empty);\n- `BETWEEN` uses `numberRangeOperand` as exactly two values `[lower, upper]`.\n",
        "required": [
          "property",
          "operator"
        ],
        "properties": {
          "property": {
            "type": "string",
            "description": "The event property to filter on.",
            "example": "plan"
          },
          "operator": {
            "type": "string",
            "enum": [
              "EQUAL",
              "GREATER_THAN",
              "LESS_THAN",
              "BETWEEN",
              "STRING_EQUAL",
              "CONTAINS",
              "STARTS_WITH",
              "STRING_IN_LIST",
              "BOOLEAN_EQUAL"
            ],
            "description": "Comparison operator."
          },
          "inverted": {
            "type": "boolean",
            "description": "When `true`, the operator is negated (e.g. NOT EQUAL).",
            "default": false
          },
          "secondOperand": {
            "type": "string",
            "nullable": true,
            "description": "Single-value operand (for scalar operators).",
            "example": "premium"
          },
          "stringInListOperand": {
            "type": "array",
            "nullable": true,
            "minItems": 1,
            "description": "Operand for the list operator (`STRING_IN_LIST`). Required and non-empty for that operator.",
            "items": {
              "type": "string"
            }
          },
          "numberRangeOperand": {
            "type": "array",
            "nullable": true,
            "minItems": 2,
            "maxItems": 2,
            "description": "Operand for the range operator (`BETWEEN`) — exactly two values, `[lower, upper]`.",
            "items": {
              "type": "number",
              "format": "double"
            }
          }
        }
      },
      "MetricCap": {
        "type": "object",
        "description": "Optional outlier/cap configuration. Each field bounds a specific measured quantity when the\nmetric is computed; a field value of `0` (the default) means that cap is not applied, so any\nfield may be omitted. In practice only the field matching the metric's `aggregation` is\nmeaningful — setting caps that don't correspond to the aggregation has no effect rather than\nbeing rejected. `granularity` is the time window the caps apply over.\n",
        "properties": {
          "baseEventCountCap": {
            "type": "number",
            "format": "double",
            "description": "Upper bound on the base-event count. `0` = no cap."
          },
          "baseEventSumCap": {
            "type": "number",
            "format": "double",
            "description": "Upper bound on the summed base-event value. `0` = no cap."
          },
          "baseEventValueCap": {
            "type": "number",
            "format": "double",
            "description": "Upper bound on an individual base-event value. `0` = no cap."
          },
          "filterEventCountCap": {
            "type": "number",
            "format": "double",
            "description": "Upper bound on the filter-event count. `0` = no cap."
          },
          "filterEventSumCap": {
            "type": "number",
            "format": "double",
            "description": "Upper bound on the summed filter-event value. `0` = no cap."
          },
          "filterEventValueCap": {
            "type": "number",
            "format": "double",
            "description": "Upper bound on an individual filter-event value. `0` = no cap."
          },
          "metricValueCap": {
            "type": "number",
            "format": "double",
            "description": "Upper bound on the final per-unit metric value. `0` = no cap."
          },
          "granularity": {
            "type": "string",
            "enum": [
              "MINUTES",
              "HOURS",
              "DAYS",
              "WEEKS"
            ],
            "default": "DAYS",
            "description": "Time window the caps apply over."
          }
        }
      },
      "MetricResponse": {
        "type": "object",
        "description": "Metric mutation response envelope. Returned by create and update: the resulting entity\ntogether with the OPA governance result. Metrics are not a governed entity type, so\n`governance` is always present with `status: NONE` and empty `details` (no policy\nevaluation occurs); the envelope is kept for response-shape consistency with other v4\nresources.\n",
        "required": [
          "entity",
          "governance"
        ],
        "properties": {
          "entity": {
            "$ref": "#/components/schemas/Metric"
          },
          "governance": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GovernanceResult"
              }
            ],
            "description": "OPA governance result for the mutation. For metrics this is always `{ \"status\": \"NONE\",\n\"details\": [] }` — `METRIC` is not a governed entity type, so no policy evaluation\noccurs. Present (never `null`) for response-shape consistency with other v4 resources.\n"
          }
        }
      },
      "MetricListResponse": {
        "type": "object",
        "description": "Paginated list of Metrics matching the query.",
        "required": [
          "data",
          "limit",
          "offset",
          "totalCount"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Metric"
            }
          },
          "limit": {
            "type": "integer",
            "description": "The page size used for this response."
          },
          "offset": {
            "type": "integer",
            "description": "The number of items skipped before the first result."
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of metrics matching the query."
          }
        }
      },
      "CreateMetricRequest": {
        "type": "object",
        "description": "Request body for creating a new Metric.",
        "required": [
          "name",
          "trafficType",
          "format",
          "aggregation",
          "isPositive",
          "baseEventTypes"
        ],
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^[A-Za-z][-_A-Za-z0-9]*$",
            "minLength": 1,
            "maxLength": 100,
            "description": "Unique metric name within the project. Immutable after creation.",
            "example": "checkout-conversion"
          },
          "description": {
            "type": "string",
            "description": "Human-readable description of this metric.",
            "example": "Conversion rate for the new checkout flow"
          },
          "trafficType": {
            "type": "string",
            "description": "Traffic type this metric measures, identified by its name (for example `user` or\n`account`). Immutable after creation.\n",
            "example": "user"
          },
          "format": {
            "type": "string",
            "enum": [
              "NUMBER",
              "DOLLAR",
              "PERCENTAGE",
              "SECONDS",
              "MILLISECONDS",
              "BYTES"
            ]
          },
          "aggregation": {
            "type": "string",
            "enum": [
              "TOTAL",
              "COUNT",
              "RATE",
              "AVERAGE",
              "NONE"
            ]
          },
          "isPositive": {
            "type": "boolean",
            "description": "`true` when an increase in this metric is a good outcome."
          },
          "spread": {
            "type": "string",
            "enum": [
              "PER",
              "ACROSS"
            ],
            "description": "Whether the metric is computed per-unit or across the population. Optional — defaults to\n`PER` when omitted (matching the current UI, which always sends `PER`).\n"
          },
          "baseEventTypes": {
            "type": "array",
            "minItems": 1,
            "description": "The base event type(s) this metric measures. At least one.",
            "items": {
              "$ref": "#/components/schemas/BaseEventType"
            }
          },
          "filterEventType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/FilterEventType"
              }
            ],
            "type": "object",
            "nullable": true
          },
          "triggerEventType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TriggerEventType"
              }
            ],
            "type": "object",
            "nullable": true,
            "description": "Optional trigger event (HAS_DONE_BEFORE): the unit must have done this event before the\nbase event for it to be counted.\n"
          },
          "tags": {
            "type": "array",
            "description": "Initial tags to associate with the metric. Uses the shared `TagReferenceInput`\n(`{ name }`); tags are returned as full `{ type, id, name }` refs on read.\n",
            "items": {
              "$ref": "#/components/schemas/TagReferenceInput"
            }
          },
          "owners": {
            "type": "array",
            "description": "Owners for this metric (optional). Uses the shared `OwnerReferenceInput`: a `USER` owner\nis `{ type: USER, id | email }`, a `GROUP` owner is `{ type: GROUP, identifier }`. Owners\nare returned as full `{ type, id, name, email }` refs on read (`email` for users only).\n",
            "items": {
              "$ref": "#/components/schemas/OwnerReferenceInput"
            }
          },
          "cap": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MetricCap"
              }
            ],
            "description": "Optional outlier/cap configuration. Set the field matching the metric's `aggregation`\n(the others stay `0` = no cap); omit entirely for an uncapped metric.\n"
          }
        },
        "example": {
          "name": "checkout-conversion",
          "description": "Conversion rate for the new checkout flow",
          "trafficType": "user",
          "format": "PERCENTAGE",
          "aggregation": "COUNT",
          "isPositive": true,
          "spread": "PER",
          "baseEventTypes": [
            {
              "eventTypeId": "checkout_completed",
              "propertyFilters": []
            }
          ],
          "tags": [
            {
              "name": "checkout"
            }
          ],
          "owners": [
            {
              "type": "USER",
              "email": "alice@example.com"
            }
          ]
        }
      },
      "UpdateMetricRequest": {
        "type": "object",
        "description": "JSON Merge Patch body (RFC 7386) for updating a Metric. Omitted fields are unchanged; `null`\nclears a nullable field; array fields are replaced in full. See the endpoint description for\nmerge semantics and how to append to an array.\n",
        "properties": {
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Updated description. `null` clears it.",
            "example": "Updated metric description"
          },
          "format": {
            "type": "string",
            "enum": [
              "NUMBER",
              "DOLLAR",
              "PERCENTAGE",
              "SECONDS",
              "MILLISECONDS",
              "BYTES"
            ],
            "description": "Updated format. Required field — cannot be set to `null`."
          },
          "aggregation": {
            "type": "string",
            "enum": [
              "TOTAL",
              "COUNT",
              "RATE",
              "AVERAGE",
              "NONE"
            ],
            "description": "Updated aggregation. Required field — cannot be set to `null`."
          },
          "isPositive": {
            "type": "boolean",
            "description": "Updated direction. Required field — cannot be set to `null`."
          },
          "spread": {
            "type": "string",
            "enum": [
              "PER",
              "ACROSS"
            ],
            "description": "Updated spread. Can be changed between `PER` and `ACROSS`, but cannot be cleared — a\nmetric always has a spread, so `null` is not accepted.\n"
          },
          "baseEventTypes": {
            "type": "array",
            "minItems": 1,
            "description": "Replacement base-event list (full replacement — each element must be complete; there is\nno element-level merge). At least one element.\n",
            "items": {
              "$ref": "#/components/schemas/BaseEventType"
            }
          },
          "filterEventType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/FilterEventType"
              }
            ],
            "type": "object",
            "nullable": true,
            "description": "Replacement filter event, or `null` to clear."
          },
          "triggerEventType": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TriggerEventType"
              }
            ],
            "type": "object",
            "nullable": true,
            "description": "Replacement trigger event (HAS_DONE_BEFORE), or `null` to clear."
          },
          "tags": {
            "type": "array",
            "nullable": true,
            "description": "Replacement tag list (full replacement), using the shared `TagReferenceInput` (`{ name }`).\n`null` or `[]` clears all tags. Tags are returned as full `{ type, id, name }` refs on read.\n",
            "items": {
              "$ref": "#/components/schemas/TagReferenceInput"
            }
          },
          "owners": {
            "type": "array",
            "nullable": true,
            "description": "Replacement owner list (full replacement), using the shared `OwnerReferenceInput`\n(`{ type: USER, id | email }` or `{ type: GROUP, identifier }`). `null` or `[]` clears all\nowners. Owners are returned as full `{ type, id, name, email }` refs on read (`email` for\nusers only).\n",
            "items": {
              "$ref": "#/components/schemas/OwnerReferenceInput"
            }
          },
          "cap": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MetricCap"
              }
            ],
            "type": "object",
            "nullable": true,
            "description": "Replacement cap configuration, or `null` to clear it (reset to no cap). Set the field\nmatching the metric's `aggregation`; the others stay `0`.\n"
          }
        },
        "example": {
          "description": "Updated metric description",
          "tags": [
            {
              "name": "checkout"
            },
            {
              "name": "q3"
            }
          ],
          "owners": [
            {
              "type": "GROUP",
              "identifier": "platform-team"
            }
          ]
        }
      }
    },
    "parameters": {
      "AccountId": {
        "name": "account_id",
        "in": "query",
        "required": true,
        "description": "Harness account identifier. Required on all endpoints.",
        "schema": {
          "type": "string",
          "pattern": "^[-_A-Za-z0-9]+$",
          "maxLength": 128,
          "example": "{{accountId}}"
        }
      },
      "OrganizationIdentifier": {
        "name": "organization_identifier",
        "in": "query",
        "required": true,
        "description": "Harness organization identifier.",
        "schema": {
          "type": "string",
          "pattern": "^[-_A-Za-z0-9]+$",
          "maxLength": 128,
          "example": "default"
        }
      },
      "ProjectIdentifier": {
        "name": "project_identifier",
        "in": "query",
        "required": true,
        "description": "Harness project identifier.",
        "schema": {
          "type": "string",
          "pattern": "^[-_A-Za-z0-9]+$",
          "maxLength": 128,
          "example": "my_project"
        }
      },
      "PaginationLimitParam": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Number of items to return per page. Defaults to 100, maximum 100.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 100,
          "example": 100
        }
      },
      "PaginationOffsetParam": {
        "name": "offset",
        "in": "query",
        "required": false,
        "description": "Number of items to skip before the first returned result. Defaults to 0.",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "default": 0,
          "example": 0
        }
      },
      "FeatureFlagName": {
        "name": "feature-flag-name",
        "in": "path",
        "required": true,
        "description": "The unique name of the feature flag within the project. Names must begin with a letter\nand may contain letters, numbers, underscores, and hyphens. Use the same value that was\nsupplied as `name` when the flag was created. System-assigned ids are not accepted.\n",
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z][-_A-Za-z0-9]*$",
          "maxLength": 100,
          "example": "my-new-flag"
        }
      },
      "EnvironmentId": {
        "name": "environment_id",
        "in": "query",
        "required": true,
        "description": "Environment identifier. Scopes the request to a specific environment; combined with the\nresource name in the path it identifies a specific environment-scoped definition (e.g.,\na Feature Flag Definition or a Segment Definition).\n",
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^[-_A-Za-z0-9]+$",
          "maxLength": 128,
          "example": "ad2eb8f0-9c3a-11ed-873c-e234abaad319"
        }
      },
      "SegmentType": {
        "name": "segment_type",
        "in": "query",
        "required": true,
        "description": "Segment kind (`STANDARD`, `LARGE`, or `RULE_BASED`). Same values as JSON `segmentType`.\nOmitting or sending an unknown value returns `400`. Name lookup and list are always a\nsingle kind.\n",
        "schema": {
          "$ref": "#/components/schemas/SegmentKind"
        }
      },
      "SegmentName": {
        "name": "segment-name",
        "in": "path",
        "required": true,
        "description": "The unique name of the segment within the project. Names must begin with a letter and\nmay contain letters, numbers, underscores, and hyphens. Use the same value that was\nsupplied as `name` when the segment was created. System-assigned ids are not accepted.\n",
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z][-_A-Za-z0-9]*$",
          "maxLength": 100,
          "example": "power-users"
        }
      },
      "CommentQueryParam": {
        "name": "comment",
        "in": "query",
        "required": false,
        "description": "Optional audit comment recorded with the action. Delivered as a query parameter because\nthe endpoint has no request body. Some workspaces require a comment on this action; when\nrequired and omitted, returns `400`.\n",
        "schema": {
          "type": "string",
          "example": "Deprecated, no longer targeted"
        }
      },
      "TitleQueryParam": {
        "name": "title",
        "in": "query",
        "required": false,
        "description": "Optional audit title recorded with the action. Delivered as a query parameter because\nthe endpoint has no request body. Some workspaces require a title on this action; when\nrequired and omitted, returns `400`.\n",
        "schema": {
          "type": "string",
          "example": "Remove unused segment definition"
        }
      },
      "EnvironmentIdPath": {
        "name": "environment-id",
        "in": "path",
        "required": true,
        "description": "The system-assigned identifier of the environment. Environment names are free-form\n(may contain spaces) and are not accepted as a path parameter.\n",
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^[-_A-Za-z0-9]+$",
          "maxLength": 128,
          "example": "ad2eb8f0-9c3a-11ed-873c-e234abaad319"
        }
      },
      "EventTypeIdPath": {
        "name": "event-type-id",
        "in": "path",
        "required": true,
        "description": "Event type id — the event name assigned by the ingestion pipeline (the value sent as\n`eventTypeId` by SDKs), not a system-generated UUID.\n",
        "schema": {
          "type": "string",
          "example": "purchase"
        }
      },
      "ExperimentParentTypeParam": {
        "name": "parent_type",
        "in": "query",
        "required": true,
        "description": "Parent kind to list. `FEATURE_FLAG` and `AI_CONFIG` are implemented. `CONFIG` is\nreserved; `parent_type=CONFIG` returns `404` in v1.\n",
        "schema": {
          "$ref": "#/components/schemas/ExperimentParentType"
        },
        "example": "FEATURE_FLAG"
      },
      "RequiredEnvironmentIdParam": {
        "name": "environment_id",
        "in": "query",
        "required": true,
        "description": "Environment the experiment is assigned in.",
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^[-_A-Za-z0-9]+$",
          "maxLength": 128,
          "example": "ad2eb8f0-9c3a-11ed-873c-e234abaad319"
        }
      },
      "OptionalEnvironmentIdParam": {
        "name": "environment_id",
        "in": "query",
        "required": false,
        "description": "Filter to experiments assigned in this environment.",
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^[-_A-Za-z0-9]+$",
          "maxLength": 128,
          "example": "ad2eb8f0-9c3a-11ed-873c-e234abaad319"
        }
      },
      "ExperimentIdPath": {
        "name": "experiment-id",
        "in": "path",
        "required": true,
        "description": "The system-assigned identifier (ULID) of the experiment.",
        "schema": {
          "type": "string",
          "format": "ulid",
          "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
          "maxLength": 128,
          "example": "01JAFXNTQHH8QTPTWYSG8H04Y5"
        }
      },
      "MetricIdPath": {
        "name": "metric-id",
        "in": "path",
        "required": true,
        "description": "The system-assigned identifier (UUID) of the metric.",
        "schema": {
          "type": "string",
          "format": "uuid",
          "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad Request — validation errors or invalid state transition.\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "validationError": {
                "summary": "Validation error",
                "value": {
                  "type": "https://developer.harness.io/docs/api-reference/errors#validation-error",
                  "status": 400,
                  "title": "Validation Error",
                  "errorType": "validationError",
                  "detail": "One or more fields failed validation",
                  "instance": "/v4/feature-flags",
                  "errors": [
                    {
                      "errorType": "requiredField",
                      "title": "Required field missing",
                      "detail": "Field 'name' is required"
                    }
                  ]
                }
              },
              "invalidState": {
                "summary": "Invalid state transition",
                "value": {
                  "type": "https://developer.harness.io/docs/api-reference/errors#invalid-state",
                  "status": 400,
                  "title": "Invalid State",
                  "errorType": "invalidState",
                  "detail": "Feature flag is already archived",
                  "instance": "/v4/feature-flags/my-flag"
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized — the request is missing a valid API key, or the key has expired.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "type": "https://developer.harness.io/docs/api-reference/errors#unauthorized",
              "status": 401,
              "title": "Unauthorized",
              "errorType": "unauthorized",
              "detail": "Missing or invalid API key",
              "instance": "/v4/environments"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden — the caller is authenticated but not permitted to perform this operation.\nReturned when the API can deny the operation without leaking whether a resource exists,\nsuch as create, or write operations where the caller can already read the resource. When\nreturning `403` would reveal resource existence, the API returns `404` instead.\n\nEnvironment-scoped mutations that require approval also return `403`.\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "type": "https://developer.harness.io/docs/api-reference/errors#forbidden",
              "status": 403,
              "title": "Forbidden",
              "errorType": "forbidden",
              "detail": "You do not have permission to perform this operation",
              "instance": "/v4/environments"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Too Many Requests — the caller has exceeded the rate limit for this endpoint.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "type": "https://developer.harness.io/docs/api-reference/errors#rate-limited",
              "status": 429,
              "title": "Too Many Requests",
              "errorType": "rateLimited",
              "detail": "Rate limit exceeded. Retry after the window resets.",
              "instance": "/v4/environments"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal Server Error — an unexpected error occurred while processing the request.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "type": "https://developer.harness.io/docs/api-reference/errors#internal-error",
              "status": 500,
              "title": "Internal Server Error",
              "errorType": "internalError",
              "detail": "An unexpected error occurred. Please retry or contact support.",
              "instance": "/v4/environments"
            }
          }
        }
      },
      "Conflict": {
        "description": "Conflict — a resource with this identifier already exists, the operation conflicts with an\nopen change request, or the resource cannot be deleted/archived while dependents still\nexist. Discriminate with `errorType`: `resourceAlreadyExists`, `pendingChangeConflict`, or\n`hasDependents`. For `hasDependents`, `detail` is the archiver message when one is\navailable; otherwise `Resource has active dependents`.\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "resourceAlreadyExists": {
                "summary": "Duplicate resource name",
                "value": {
                  "type": "https://developer.harness.io/docs/api-reference/errors#conflict",
                  "status": 409,
                  "title": "Resource Already Exists",
                  "errorType": "resourceAlreadyExists",
                  "detail": "Feature flag 'my-new-flag' already exists in project 'my_project'",
                  "instance": "/v4/feature-flags"
                }
              },
              "pendingChangeConflict": {
                "summary": "Open change request blocks the mutation",
                "value": {
                  "type": "https://developer.harness.io/docs/api-reference/errors#pending-change-conflict",
                  "status": 409,
                  "title": "Pending Change Conflict",
                  "errorType": "pendingChangeConflict",
                  "detail": "A pending rollout status change request for this object already exists",
                  "instance": "/v4/feature-flags/my-flag"
                }
              },
              "hasDependents": {
                "summary": "Resource has active dependents",
                "value": {
                  "type": "https://developer.harness.io/docs/api-reference/errors#has-dependents",
                  "status": 409,
                  "title": "Resource Has Dependents",
                  "errorType": "hasDependents",
                  "detail": "This segment can't be deleted because it still has members associated with it.",
                  "instance": "/v4/segments/my-segment"
                }
              }
            }
          }
        }
      },
      "UnprocessableEntity": {
        "description": "Unprocessable Content — OPA governance policy evaluation returned ERROR (`governanceError`).\nEach failing policy is listed in the `errors` array.\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "governanceError": {
                "summary": "Governance policy blocked the operation",
                "value": {
                  "type": "https://developer.harness.io/docs/api-reference/errors#governance-error",
                  "status": 422,
                  "title": "Governance Policy Violation",
                  "errorType": "governanceError",
                  "detail": "One or more governance policies returned ERROR",
                  "instance": "/v4/feature-flag-definitions/my-flag",
                  "errors": [
                    {
                      "errorType": "governancePolicy",
                      "title": "require-jira-link",
                      "detail": "JIRA issue reference is required"
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Not Found — the requested resource does not exist. Also returned when the caller lacks\naccess to the resource (to avoid leaking resource existence).\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "type": "https://developer.harness.io/docs/api-reference/errors#not-found",
              "status": 404,
              "title": "Not Found",
              "errorType": "notFound",
              "detail": "Feature flag 'my-nonexistent-flag' not found in project 'my_project'",
              "instance": "/v4/feature-flags/my-nonexistent-flag"
            }
          }
        }
      },
      "MetricConflict": {
        "description": "Conflict — the metric collides with an existing one. Two distinct causes are reported via\nthe RFC 7807 `errorType`:\n- `resourceAlreadyExists` — another metric already uses this `name`.\n- `duplicateDefinition` — a different-named metric with an equivalent definition already\n  exists (metrics are de-duplicated by definition, not only by name).\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "duplicateName": {
                "summary": "A metric with this name already exists",
                "value": {
                  "type": "https://developer.harness.io/docs/api-reference/errors#resource-already-exists",
                  "status": 409,
                  "title": "Resource Already Exists",
                  "errorType": "resourceAlreadyExists",
                  "detail": "A metric named 'checkout-conversion' already exists in this project.",
                  "instance": "/v4/metrics"
                }
              },
              "duplicateDefinition": {
                "summary": "An equivalent metric definition already exists under a different name",
                "value": {
                  "type": "https://developer.harness.io/docs/api-reference/errors#duplicate-definition",
                  "status": 409,
                  "title": "Duplicate Definition",
                  "errorType": "duplicateDefinition",
                  "detail": "A metric with an equivalent definition already exists under a different name.",
                  "instance": "/v4/metrics"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Harness Service Account Token (SAT) or Personal Access Token (PAT).\nGenerate tokens in Harness under Account Settings → Access Management.\n"
      }
    }
  }
}
