> For the complete documentation index, see [llms.txt](https://docs.reflag.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.reflag.com/api/reflag-rest-api/reflag-api-reference.md).

# API Reference

Describes the Management API that allows clients to manage and update apps, flags, and related entities.

## List of applications

> Retrieve all accessible applications

```json
{"openapi":"3.1.0","info":{"title":"Reflag Management API","version":"3.1.0"},"servers":[{"url":"https://app.reflag.com/api","description":"Production server"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"bearer","description":"API key authentication, for service access"}},"schemas":{"orgId":{"description":"Organization identifier","type":"string","minLength":1},"appHeaderCollection":{"description":"Collection of Basic app information","type":"object","properties":{"data":{"description":"The individual items in the collection","type":"array","items":{"$ref":"#/components/schemas/appHeader"}}},"required":["data"],"additionalProperties":false},"appHeader":{"description":"Basic app information","type":"object","properties":{"org":{"$ref":"#/components/schemas/orgHeader"},"id":{"$ref":"#/components/schemas/appId"},"name":{"description":"App name","type":"string"},"demo":{"description":"Whether the app is a demo app","type":"boolean"},"flagKeyFormat":{"$ref":"#/components/schemas/flagKeyFormat"},"environments":{"description":"Environments within the app","type":"array","items":{"$ref":"#/components/schemas/environmentHeader"}}},"required":["org","id","name","demo","flagKeyFormat","environments"],"additionalProperties":false},"orgHeader":{"description":"Organization's basic information","type":"object","properties":{"id":{"$ref":"#/components/schemas/orgId"},"name":{"description":"Organization name","type":"string","minLength":1}},"required":["id","name"],"additionalProperties":false},"appId":{"description":"App identifier","type":"string","minLength":1},"flagKeyFormat":{"description":"The enforced key format when creating flags","type":"string","enum":["custom","pascalCase","camelCase","snakeCaseUpper","snakeCaseLower","kebabCaseUpper","kebabCaseLower"]},"environmentHeader":{"description":"Basic environment information","type":"object","properties":{"id":{"$ref":"#/components/schemas/envId"},"name":{"description":"Environment name","type":"string"},"isProduction":{"description":"Whether the environment is a production environment","type":"boolean"},"order":{"description":"Environment order in the app (zero-indexed)","type":"integer"},"flagStateVersion":{"description":"Environment version incremented when flag state changes","type":"integer"}},"required":["id","name","isProduction","order","flagStateVersion"],"additionalProperties":false},"envId":{"description":"Environment identifier","type":"string","minLength":1},"ErrorResponse":{"description":"The error response, including individual issues, if applicable","type":"object","properties":{"error":{"description":"The error","type":"object","properties":{"code":{"description":"Error code","type":"string","enum":["invalid_request","not_found","not_possible","not_allowed","not_available","unknown_error","unauthorized","unauthenticated"]},"message":{"description":"Human readable error message","type":"string"}},"required":["code","message"],"additionalProperties":false},"issues":{"description":"Individual validation issues, if applicable","type":"object","propertyNames":{"description":"The field that has the issue (uses dot notation). Empty string if the issue is at the root.","type":"string"},"additionalProperties":{"description":"Error messages for this field","type":"array","items":{"description":"The error message","type":"string"}}}},"required":["error"],"additionalProperties":false}}},"paths":{"/apps":{"get":{"summary":"List of applications","description":"Retrieve all accessible applications","operationId":"listApps","parameters":[{"in":"query","name":"orgId","schema":{"$ref":"#/components/schemas/orgId"}}],"responses":{"200":{"description":"Requested resource retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/appHeaderCollection"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource, or its parent, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get details of an application

> Retrieve a specific application by its identifier

```json
{"openapi":"3.1.0","info":{"title":"Reflag Management API","version":"3.1.0"},"servers":[{"url":"https://app.reflag.com/api","description":"Production server"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"bearer","description":"API key authentication, for service access"}},"schemas":{"appId":{"description":"App identifier","type":"string","minLength":1},"app":{"description":"App information with related collections","type":"object","properties":{"org":{"$ref":"#/components/schemas/orgHeader"},"id":{"$ref":"#/components/schemas/appId"},"name":{"description":"App name","type":"string"},"demo":{"description":"Whether the app is a demo app","type":"boolean"},"flagKeyFormat":{"$ref":"#/components/schemas/flagKeyFormat"},"environments":{"description":"Environments within the app","type":"array","items":{"$ref":"#/components/schemas/environment"}},"stages":{"description":"Stages within the app","type":"array","items":{"$ref":"#/components/schemas/stageHeader"}},"segments":{"description":"Segments within the app","type":"array","items":{"$ref":"#/components/schemas/segmentHeader"}}},"required":["org","id","name","demo","flagKeyFormat","environments","stages","segments"],"additionalProperties":false},"orgHeader":{"description":"Organization's basic information","type":"object","properties":{"id":{"$ref":"#/components/schemas/orgId"},"name":{"description":"Organization name","type":"string","minLength":1}},"required":["id","name"],"additionalProperties":false},"orgId":{"description":"Organization identifier","type":"string","minLength":1},"flagKeyFormat":{"description":"The enforced key format when creating flags","type":"string","enum":["custom","pascalCase","camelCase","snakeCaseUpper","snakeCaseLower","kebabCaseUpper","kebabCaseLower"]},"environment":{"description":"Environment details","type":"object","properties":{"id":{"$ref":"#/components/schemas/envId"},"name":{"description":"Environment name","type":"string"},"isProduction":{"description":"Whether the environment is a production environment","type":"boolean"},"order":{"description":"Environment order in the app (zero-indexed)","type":"integer"},"flagStateVersion":{"description":"Environment version incremented when flag state changes","type":"integer"},"sdkAccess":{"description":"SDK access details","type":"object","properties":{"publishableKey":{"description":"Publishable key","type":"string","minLength":1,"maxLength":36},"secretKey":{"description":"Secret key","type":"string","minLength":1,"maxLength":36}},"required":["publishableKey","secretKey"],"additionalProperties":false}},"required":["id","name","isProduction","order","flagStateVersion","sdkAccess"],"additionalProperties":false},"envId":{"description":"Environment identifier","type":"string","minLength":1},"stageHeader":{"description":"Stage's basic information","type":"object","properties":{"id":{"$ref":"#/components/schemas/stageId"},"name":{"description":"Stage name","type":"string","minLength":1},"color":{"description":"Stage color (HTML color name or hex code)","type":"string","minLength":1,"maxLength":64},"order":{"description":"Stage order","type":"integer"}},"required":["id","name","color","order"],"additionalProperties":false},"stageId":{"description":"Stage identifier","type":"string","minLength":1},"segmentHeader":{"description":"Segment's basic information","type":"object","properties":{"id":{"$ref":"#/components/schemas/segmentId"},"name":{"description":"Segment name","type":"string","minLength":1},"type":{"$ref":"#/components/schemas/segmentType"}},"required":["id","name","type"],"additionalProperties":false},"segmentId":{"description":"Segment identifier","type":"string","minLength":1},"segmentType":{"description":"Segment type","type":"string","enum":["all","custom"]},"ErrorResponse":{"description":"The error response, including individual issues, if applicable","type":"object","properties":{"error":{"description":"The error","type":"object","properties":{"code":{"description":"Error code","type":"string","enum":["invalid_request","not_found","not_possible","not_allowed","not_available","unknown_error","unauthorized","unauthenticated"]},"message":{"description":"Human readable error message","type":"string"}},"required":["code","message"],"additionalProperties":false},"issues":{"description":"Individual validation issues, if applicable","type":"object","propertyNames":{"description":"The field that has the issue (uses dot notation). Empty string if the issue is at the root.","type":"string"},"additionalProperties":{"description":"Error messages for this field","type":"array","items":{"description":"The error message","type":"string"}}}},"required":["error"],"additionalProperties":false}}},"paths":{"/apps/{appId}":{"get":{"summary":"Get details of an application","description":"Retrieve a specific application by its identifier","operationId":"getApp","parameters":[{"in":"path","name":"appId","schema":{"$ref":"#/components/schemas/appId"},"required":true,"description":"App identifier"}],"responses":{"200":{"description":"Requested resource retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource, or its parent, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## List flags for application

> Retrieve all flags for a specific application

```json
{"openapi":"3.1.0","info":{"title":"Reflag Management API","version":"3.1.0"},"servers":[{"url":"https://app.reflag.com/api","description":"Production server"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"bearer","description":"API key authentication, for service access"}},"schemas":{"appId":{"description":"App identifier","type":"string","minLength":1},"flagHeaderCollection":{"description":"Collection response containing flags","type":"object","properties":{"data":{"description":"Page of the collection of flags","type":"array","items":{"$ref":"#/components/schemas/flagHeader"}},"totalCount":{"description":"Total number of flags in collection","type":"integer"},"pageSize":{"description":"Page size","type":"integer"},"pageIndex":{"description":"Page index","type":"integer"},"sortBy":{"description":"Sort by","type":"string","enum":["name","key","stage","autoFeedbackSurveysEnabled","createdAt","rolledOutToEveryoneAt","environmentStatus","owner","lastCheck","lastTrack","stale","archivingChecks"]},"sortOrder":{"description":"Sort order","$ref":"#/components/schemas/sortOrder"}},"required":["data","totalCount","pageSize","pageIndex","sortBy","sortOrder"],"additionalProperties":false},"flagHeader":{"description":"Basic flag information","type":"object","properties":{"id":{"$ref":"#/components/schemas/flagId"},"key":{"$ref":"#/components/schemas/flagKey"},"name":{"description":"Flag name","type":"string","minLength":1,"maxLength":255},"description":{"description":"Flag description","type":"string"},"stage":{"$ref":"#/components/schemas/stageHeader"},"owner":{"$ref":"#/components/schemas/reflagUserHeader"},"archived":{"description":"Whether the flag is archived","type":"boolean"},"stale":{"description":"Whether the flag is stale","type":"boolean"},"permanent":{"description":"Whether the flag is permanent","type":"boolean"},"createdAt":{"description":"Timestamp when the flag was created","type":"string"},"rolledOutToEveryoneAt":{"description":"Timestamp when the flag was rolled out to everyone","type":"string"},"codeRefsCleanedUp":{"description":"Whether code references for this flag have been cleaned up","type":"boolean"},"codeRefsMarkedCleanUserName":{"description":"Name of the user who marked code references as cleaned up","type":"string"},"codeRefsMarkedCleanAt":{"description":"Timestamp when code references were marked as cleaned up","type":"string"},"lastCheckAt":{"description":"Timestamp when the flag was last checked","type":"string"},"noRecentChecks":{"description":"Whether the flag has no recent access checks","type":"boolean"},"lastTrackAt":{"description":"Timestamp when the flag was last tracked","type":"string"}},"required":["id","key","name","archived","stale","permanent","codeRefsCleanedUp","noRecentChecks"],"additionalProperties":false},"flagId":{"description":"Flag ID","type":"string","minLength":1},"flagKey":{"description":"Unique flag key","type":"string","minLength":1},"stageHeader":{"description":"Stage's basic information","type":"object","properties":{"id":{"$ref":"#/components/schemas/stageId"},"name":{"description":"Stage name","type":"string","minLength":1},"color":{"description":"Stage color (HTML color name or hex code)","type":"string","minLength":1,"maxLength":64},"order":{"description":"Stage order","type":"integer"}},"required":["id","name","color","order"],"additionalProperties":false},"stageId":{"description":"Stage identifier","type":"string","minLength":1},"reflagUserHeader":{"description":"Reflag user's basic information","type":"object","properties":{"id":{"$ref":"#/components/schemas/reflagUserId"},"name":{"description":"User's name","type":"string","minLength":1},"email":{"description":"User's email","type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"avatarUrl":{"description":"User's avatar URL","type":"string","format":"uri"}},"required":["id","name","email"],"additionalProperties":false},"reflagUserId":{"description":"Reflag user identifier","type":"string","minLength":1},"sortOrder":{"description":"Sort order applied to the sorting column","default":"asc","type":"string","enum":["asc","desc"]},"ErrorResponse":{"description":"The error response, including individual issues, if applicable","type":"object","properties":{"error":{"description":"The error","type":"object","properties":{"code":{"description":"Error code","type":"string","enum":["invalid_request","not_found","not_possible","not_allowed","not_available","unknown_error","unauthorized","unauthenticated"]},"message":{"description":"Human readable error message","type":"string"}},"required":["code","message"],"additionalProperties":false},"issues":{"description":"Individual validation issues, if applicable","type":"object","propertyNames":{"description":"The field that has the issue (uses dot notation). Empty string if the issue is at the root.","type":"string"},"additionalProperties":{"description":"Error messages for this field","type":"array","items":{"description":"The error message","type":"string"}}}},"required":["error"],"additionalProperties":false}}},"paths":{"/apps/{appId}/flags":{"get":{"summary":"List flags for application","description":"Retrieve all flags for a specific application","operationId":"listFlags","parameters":[{"in":"path","name":"appId","schema":{"$ref":"#/components/schemas/appId"},"required":true,"description":"App identifier"}],"responses":{"200":{"description":"Requested resource retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/flagHeaderCollection"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource, or its parent, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## List environments for application

> Retrieve all environments for a specific application

```json
{"openapi":"3.1.0","info":{"title":"Reflag Management API","version":"3.1.0"},"servers":[{"url":"https://app.reflag.com/api","description":"Production server"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"bearer","description":"API key authentication, for service access"}},"schemas":{"appId":{"description":"App identifier","type":"string","minLength":1},"sortOrder":{"description":"Sort order applied to the sorting column","default":"asc","type":"string","enum":["asc","desc"]},"environmentHeaderSortByColumn":{"description":"The column to sort by","default":"order","type":"string","enum":["name","order"]},"environmentHeaderCollection":{"description":"Collection of Basic environment information","type":"object","properties":{"data":{"description":"The individual items in the collection","type":"array","items":{"$ref":"#/components/schemas/environmentHeader"}},"sortOrder":{"$ref":"#/components/schemas/sortOrder"},"sortBy":{"$ref":"#/components/schemas/environmentHeaderSortByColumn"}},"required":["data","sortOrder","sortBy"],"additionalProperties":false},"environmentHeader":{"description":"Basic environment information","type":"object","properties":{"id":{"$ref":"#/components/schemas/envId"},"name":{"description":"Environment name","type":"string"},"isProduction":{"description":"Whether the environment is a production environment","type":"boolean"},"order":{"description":"Environment order in the app (zero-indexed)","type":"integer"},"flagStateVersion":{"description":"Environment version incremented when flag state changes","type":"integer"}},"required":["id","name","isProduction","order","flagStateVersion"],"additionalProperties":false},"envId":{"description":"Environment identifier","type":"string","minLength":1},"ErrorResponse":{"description":"The error response, including individual issues, if applicable","type":"object","properties":{"error":{"description":"The error","type":"object","properties":{"code":{"description":"Error code","type":"string","enum":["invalid_request","not_found","not_possible","not_allowed","not_available","unknown_error","unauthorized","unauthenticated"]},"message":{"description":"Human readable error message","type":"string"}},"required":["code","message"],"additionalProperties":false},"issues":{"description":"Individual validation issues, if applicable","type":"object","propertyNames":{"description":"The field that has the issue (uses dot notation). Empty string if the issue is at the root.","type":"string"},"additionalProperties":{"description":"Error messages for this field","type":"array","items":{"description":"The error message","type":"string"}}}},"required":["error"],"additionalProperties":false}}},"paths":{"/apps/{appId}/environments":{"get":{"summary":"List environments for application","description":"Retrieve all environments for a specific application","operationId":"listEnvironments","parameters":[{"in":"path","name":"appId","schema":{"$ref":"#/components/schemas/appId"},"required":true,"description":"App identifier"},{"in":"query","name":"sortOrder","schema":{"$ref":"#/components/schemas/sortOrder"},"description":"Sort order applied to the sorting column"},{"in":"query","name":"sortBy","schema":{"$ref":"#/components/schemas/environmentHeaderSortByColumn"},"description":"The column to sort by"}],"responses":{"200":{"description":"Requested resource retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/environmentHeaderCollection"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource, or its parent, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get environment details

> Retrieve details for a specific environment

```json
{"openapi":"3.1.0","info":{"title":"Reflag Management API","version":"3.1.0"},"servers":[{"url":"https://app.reflag.com/api","description":"Production server"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"bearer","description":"API key authentication, for service access"}},"schemas":{"appId":{"description":"App identifier","type":"string","minLength":1},"envId":{"description":"Environment identifier","type":"string","minLength":1},"environment":{"description":"Environment details","type":"object","properties":{"id":{"$ref":"#/components/schemas/envId"},"name":{"description":"Environment name","type":"string"},"isProduction":{"description":"Whether the environment is a production environment","type":"boolean"},"order":{"description":"Environment order in the app (zero-indexed)","type":"integer"},"flagStateVersion":{"description":"Environment version incremented when flag state changes","type":"integer"},"sdkAccess":{"description":"SDK access details","type":"object","properties":{"publishableKey":{"description":"Publishable key","type":"string","minLength":1,"maxLength":36},"secretKey":{"description":"Secret key","type":"string","minLength":1,"maxLength":36}},"required":["publishableKey","secretKey"],"additionalProperties":false}},"required":["id","name","isProduction","order","flagStateVersion","sdkAccess"],"additionalProperties":false},"ErrorResponse":{"description":"The error response, including individual issues, if applicable","type":"object","properties":{"error":{"description":"The error","type":"object","properties":{"code":{"description":"Error code","type":"string","enum":["invalid_request","not_found","not_possible","not_allowed","not_available","unknown_error","unauthorized","unauthenticated"]},"message":{"description":"Human readable error message","type":"string"}},"required":["code","message"],"additionalProperties":false},"issues":{"description":"Individual validation issues, if applicable","type":"object","propertyNames":{"description":"The field that has the issue (uses dot notation). Empty string if the issue is at the root.","type":"string"},"additionalProperties":{"description":"Error messages for this field","type":"array","items":{"description":"The error message","type":"string"}}}},"required":["error"],"additionalProperties":false}}},"paths":{"/apps/{appId}/environments/{envId}":{"get":{"summary":"Get environment details","description":"Retrieve details for a specific environment","operationId":"getEnvironment","parameters":[{"in":"path","name":"appId","schema":{"$ref":"#/components/schemas/appId"},"required":true,"description":"App identifier"},{"in":"path","name":"envId","schema":{"$ref":"#/components/schemas/envId"},"required":true,"description":"Environment identifier"}],"responses":{"200":{"description":"Requested resource retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/environment"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource, or its parent, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create a flag

> Create a new flag in the application. Returns the created flag and the resulting flag-state version for every environment.

```json
{"openapi":"3.1.0","info":{"title":"Reflag Management API","version":"3.1.0"},"servers":[{"url":"https://app.reflag.com/api","description":"Production server"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"bearer","description":"API key authentication, for service access"}},"schemas":{"appId":{"description":"App identifier","type":"string","minLength":1},"flagId":{"description":"Flag ID","type":"string","minLength":1},"flagKey":{"description":"Unique flag key","type":"string","minLength":1},"stageHeader":{"description":"Stage's basic information","type":"object","properties":{"id":{"$ref":"#/components/schemas/stageId"},"name":{"description":"Stage name","type":"string","minLength":1},"color":{"description":"Stage color (HTML color name or hex code)","type":"string","minLength":1,"maxLength":64},"order":{"description":"Stage order","type":"integer"}},"required":["id","name","color","order"],"additionalProperties":false},"stageId":{"description":"Stage identifier","type":"string","minLength":1},"reflagUserHeader":{"description":"Reflag user's basic information","type":"object","properties":{"id":{"$ref":"#/components/schemas/reflagUserId"},"name":{"description":"User's name","type":"string","minLength":1},"email":{"description":"User's email","type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"avatarUrl":{"description":"User's avatar URL","type":"string","format":"uri"}},"required":["id","name","email"],"additionalProperties":false},"reflagUserId":{"description":"Reflag user identifier","type":"string","minLength":1},"appFlagStateVersions":{"description":"Current flag-state version keyed by environment ID","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/components/schemas/flagStateVersion"}},"flagStateVersion":{"description":"Environment flag-state version containing the completed mutation","type":"integer","minimum":0},"ErrorResponse":{"description":"The error response, including individual issues, if applicable","type":"object","properties":{"error":{"description":"The error","type":"object","properties":{"code":{"description":"Error code","type":"string","enum":["invalid_request","not_found","not_possible","not_allowed","not_available","unknown_error","unauthorized","unauthenticated"]},"message":{"description":"Human readable error message","type":"string"}},"required":["code","message"],"additionalProperties":false},"issues":{"description":"Individual validation issues, if applicable","type":"object","propertyNames":{"description":"The field that has the issue (uses dot notation). Empty string if the issue is at the root.","type":"string"},"additionalProperties":{"description":"Error messages for this field","type":"array","items":{"description":"The error message","type":"string"}}}},"required":["error"],"additionalProperties":false}}},"paths":{"/apps/{appId}/flags":{"post":{"summary":"Create a flag","description":"Create a new flag in the application. Returns the created flag and the resulting flag-state version for every environment.","operationId":"createFlag","parameters":[{"in":"path","name":"appId","schema":{"$ref":"#/components/schemas/appId"},"required":true,"description":"App identifier"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"description":"Key of the flag","type":"string","minLength":1},"name":{"description":"Name of the flag","type":"string","minLength":1},"description":{"description":"Description of the flag","anyOf":[{"type":"string","maxLength":8192},{"type":"null"}]},"stageId":{"description":"Stage ID of the flag","type":"string","minLength":14,"maxLength":14},"ownerUserId":{"anyOf":[{"type":"string"},{"type":"null"}]},"permanent":{"default":false,"type":"boolean"},"secret":{"description":"Whether the flag is secret","type":"boolean"}},"required":["key","name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Requested resource retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"flag":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/flagId"},"key":{"$ref":"#/components/schemas/flagKey"},"name":{"description":"Flag name","type":"string","minLength":1,"maxLength":255},"description":{"description":"Flag description","type":"string"},"stage":{"$ref":"#/components/schemas/stageHeader"},"owner":{"$ref":"#/components/schemas/reflagUserHeader"},"archived":{"description":"Whether the flag is archived","type":"boolean"},"stale":{"description":"Whether the flag is stale","type":"boolean"},"permanent":{"description":"Whether the flag is permanent","type":"boolean"},"createdAt":{"description":"Timestamp when the flag was created","type":"string"},"rolledOutToEveryoneAt":{"description":"Timestamp when the flag was rolled out to everyone","type":"string"},"codeRefsCleanedUp":{"description":"Whether code references for this flag have been cleaned up","type":"boolean"},"codeRefsMarkedCleanUserName":{"description":"Name of the user who marked code references as cleaned up","type":"string"},"codeRefsMarkedCleanAt":{"description":"Timestamp when code references were marked as cleaned up","type":"string"},"lastCheckAt":{"description":"Timestamp when the flag was last checked","type":"string"},"noRecentChecks":{"description":"Whether the flag has no recent access checks","type":"boolean"},"lastTrackAt":{"description":"Timestamp when the flag was last tracked","type":"string"},"parentFlagId":{"description":"Parent flag ID","type":"string"}},"required":["id","key","name","archived","stale","permanent","codeRefsCleanedUp","noRecentChecks"],"additionalProperties":false},"flagStateVersions":{"$ref":"#/components/schemas/appFlagStateVersions"}},"required":["flag","flagStateVersions"],"additionalProperties":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource, or its parent, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Update a flag

> Update an existing flag. Returns the current flag-state version for every environment, including any versions advanced by this update.

```json
{"openapi":"3.1.0","info":{"title":"Reflag Management API","version":"3.1.0"},"servers":[{"url":"https://app.reflag.com/api","description":"Production server"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"bearer","description":"API key authentication, for service access"}},"schemas":{"appId":{"description":"App identifier","type":"string","minLength":1},"flagId":{"description":"Flag ID","type":"string","minLength":1},"flagKey":{"description":"Unique flag key","type":"string","minLength":1},"stageHeader":{"description":"Stage's basic information","type":"object","properties":{"id":{"$ref":"#/components/schemas/stageId"},"name":{"description":"Stage name","type":"string","minLength":1},"color":{"description":"Stage color (HTML color name or hex code)","type":"string","minLength":1,"maxLength":64},"order":{"description":"Stage order","type":"integer"}},"required":["id","name","color","order"],"additionalProperties":false},"stageId":{"description":"Stage identifier","type":"string","minLength":1},"reflagUserHeader":{"description":"Reflag user's basic information","type":"object","properties":{"id":{"$ref":"#/components/schemas/reflagUserId"},"name":{"description":"User's name","type":"string","minLength":1},"email":{"description":"User's email","type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"avatarUrl":{"description":"User's avatar URL","type":"string","format":"uri"}},"required":["id","name","email"],"additionalProperties":false},"reflagUserId":{"description":"Reflag user identifier","type":"string","minLength":1},"appFlagStateVersions":{"description":"Current flag-state version keyed by environment ID","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/components/schemas/flagStateVersion"}},"flagStateVersion":{"description":"Environment flag-state version containing the completed mutation","type":"integer","minimum":0},"ErrorResponse":{"description":"The error response, including individual issues, if applicable","type":"object","properties":{"error":{"description":"The error","type":"object","properties":{"code":{"description":"Error code","type":"string","enum":["invalid_request","not_found","not_possible","not_allowed","not_available","unknown_error","unauthorized","unauthenticated"]},"message":{"description":"Human readable error message","type":"string"}},"required":["code","message"],"additionalProperties":false},"issues":{"description":"Individual validation issues, if applicable","type":"object","propertyNames":{"description":"The field that has the issue (uses dot notation). Empty string if the issue is at the root.","type":"string"},"additionalProperties":{"description":"Error messages for this field","type":"array","items":{"description":"The error message","type":"string"}}}},"required":["error"],"additionalProperties":false}}},"paths":{"/apps/{appId}/flags/{flagId}":{"patch":{"summary":"Update a flag","description":"Update an existing flag. Returns the current flag-state version for every environment, including any versions advanced by this update.","operationId":"updateFlag","parameters":[{"in":"path","name":"appId","schema":{"$ref":"#/components/schemas/appId"},"required":true,"description":"App identifier"},{"in":"path","name":"flagId","schema":{"$ref":"#/components/schemas/flagId"},"required":true,"description":"Flag ID"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"Name of the flag","type":"string","minLength":1},"description":{"description":"Description of the flag","anyOf":[{"type":"string","maxLength":8192},{"type":"null"}]},"ownerUserId":{"anyOf":[{"type":"string"},{"type":"null"}]},"permanent":{"type":"boolean"},"secret":{"description":"Whether the flag is secret","type":"boolean"},"isArchived":{"type":"boolean"},"stageId":{"description":"Stage ID of the flag","type":"string","minLength":14,"maxLength":14}},"additionalProperties":false}}}},"responses":{"200":{"description":"Requested resource retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"flag":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/flagId"},"key":{"$ref":"#/components/schemas/flagKey"},"name":{"description":"Flag name","type":"string","minLength":1,"maxLength":255},"description":{"description":"Flag description","type":"string"},"stage":{"$ref":"#/components/schemas/stageHeader"},"owner":{"$ref":"#/components/schemas/reflagUserHeader"},"archived":{"description":"Whether the flag is archived","type":"boolean"},"stale":{"description":"Whether the flag is stale","type":"boolean"},"permanent":{"description":"Whether the flag is permanent","type":"boolean"},"createdAt":{"description":"Timestamp when the flag was created","type":"string"},"rolledOutToEveryoneAt":{"description":"Timestamp when the flag was rolled out to everyone","type":"string"},"codeRefsCleanedUp":{"description":"Whether code references for this flag have been cleaned up","type":"boolean"},"codeRefsMarkedCleanUserName":{"description":"Name of the user who marked code references as cleaned up","type":"string"},"codeRefsMarkedCleanAt":{"description":"Timestamp when code references were marked as cleaned up","type":"string"},"lastCheckAt":{"description":"Timestamp when the flag was last checked","type":"string"},"noRecentChecks":{"description":"Whether the flag has no recent access checks","type":"boolean"},"lastTrackAt":{"description":"Timestamp when the flag was last tracked","type":"string"},"parentFlagId":{"description":"Parent flag ID","type":"string"}},"required":["id","key","name","archived","stale","permanent","codeRefsCleanedUp","noRecentChecks"],"additionalProperties":false},"flagStateVersions":{"$ref":"#/components/schemas/appFlagStateVersions"}},"required":["flag","flagStateVersions"],"additionalProperties":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource, or its parent, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get flags for a company

> Retrieve all flags with their targeting status for a specific company

```json
{"openapi":"3.1.0","info":{"title":"Reflag Management API","version":"3.1.0"},"servers":[{"url":"https://app.reflag.com/api","description":"Production server"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"bearer","description":"API key authentication, for service access"}},"schemas":{"appId":{"description":"App identifier","type":"string","minLength":1},"envId":{"description":"Environment identifier","type":"string","minLength":1},"companyId":{"description":"Company ID within your application","type":"string","minLength":1,"maxLength":128},"entityFlagsResponse":{"description":"Response containing flags for an entity","type":"object","properties":{"data":{"description":"List of flags with their enabled status","type":"array","items":{"$ref":"#/components/schemas/entityFlag"}},"totalCount":{"description":"Total number of flags","type":"integer"},"pageSize":{"description":"Page size","type":"integer"},"pageIndex":{"description":"Page index","type":"integer"}},"required":["data","totalCount","pageSize","pageIndex"],"additionalProperties":false},"entityFlag":{"description":"Flag information with enabled status for an entity","type":"object","properties":{"id":{"$ref":"#/components/schemas/flagId"},"key":{"$ref":"#/components/schemas/flagKey"},"name":{"description":"Flag name","type":"string","minLength":1,"maxLength":255},"createdAt":{"description":"Timestamp when the flag was created","type":"string"},"value":{"description":"Whether the flag is enabled for this entity","type":"boolean"},"specificTargetValue":{"description":"Value if directly added via specific targets, null if not specifically targeted","anyOf":[{"type":"boolean"},{"type":"null"}]},"firstExposureAt":{"description":"First time the entity was exposed to this flag","anyOf":[{"type":"string"},{"type":"null"}]},"lastExposureAt":{"description":"Last time the entity was exposed to this flag","anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckAt":{"description":"Last time the flag was checked for this entity","anyOf":[{"type":"string"},{"type":"null"}]},"exposureCount":{"description":"Number of times the entity was exposed to this flag","type":"integer"},"firstTrackAt":{"description":"First time a track event was recorded for this flag","anyOf":[{"type":"string"},{"type":"null"}]},"lastTrackAt":{"description":"Last time a track event was recorded for this flag","anyOf":[{"type":"string"},{"type":"null"}]},"trackCount":{"description":"Number of track events for this flag","type":"integer"}},"required":["id","key","name","createdAt","value","specificTargetValue","firstExposureAt","lastExposureAt","lastCheckAt","exposureCount","firstTrackAt","lastTrackAt","trackCount"],"additionalProperties":false},"flagId":{"description":"Flag ID","type":"string","minLength":1},"flagKey":{"description":"Unique flag key","type":"string","minLength":1},"ErrorResponse":{"description":"The error response, including individual issues, if applicable","type":"object","properties":{"error":{"description":"The error","type":"object","properties":{"code":{"description":"Error code","type":"string","enum":["invalid_request","not_found","not_possible","not_allowed","not_available","unknown_error","unauthorized","unauthenticated"]},"message":{"description":"Human readable error message","type":"string"}},"required":["code","message"],"additionalProperties":false},"issues":{"description":"Individual validation issues, if applicable","type":"object","propertyNames":{"description":"The field that has the issue (uses dot notation). Empty string if the issue is at the root.","type":"string"},"additionalProperties":{"description":"Error messages for this field","type":"array","items":{"description":"The error message","type":"string"}}}},"required":["error"],"additionalProperties":false}}},"paths":{"/apps/{appId}/envs/{envId}/companies/{companyId}/flags":{"get":{"summary":"Get flags for a company","description":"Retrieve all flags with their targeting status for a specific company","operationId":"getCompanyFlags","parameters":[{"in":"path","name":"appId","schema":{"$ref":"#/components/schemas/appId"},"required":true,"description":"App identifier"},{"in":"path","name":"envId","schema":{"$ref":"#/components/schemas/envId"},"required":true,"description":"Environment identifier"},{"in":"path","name":"companyId","schema":{"$ref":"#/components/schemas/companyId"},"required":true,"description":"Company ID within your application"}],"responses":{"200":{"description":"Requested resource retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/entityFlagsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource, or its parent, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Update flag targeting for a company

> Update specific targeting for flags for a company in an environment. Returns the environment flag-state version containing the completed update.

```json
{"openapi":"3.1.0","info":{"title":"Reflag Management API","version":"3.1.0"},"servers":[{"url":"https://app.reflag.com/api","description":"Production server"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"bearer","description":"API key authentication, for service access"}},"schemas":{"appId":{"description":"App identifier","type":"string","minLength":1},"envId":{"description":"Environment identifier","type":"string","minLength":1},"companyId":{"description":"Company ID within your application","type":"string","minLength":1,"maxLength":128},"updateEntityFlagsBody":{"description":"Request body for updating flags for an entity","type":"object","properties":{"updates":{"description":"List of flag updates to apply","minItems":1,"type":"array","items":{"$ref":"#/components/schemas/entityFlagUpdate"}},"changeDescription":{"description":"Description of the change for audit history","type":"string"},"notifications":{"description":"Destination list for notifications about the change. Use [] to disable notifications. Omit to use configured defaults.","type":"array","items":{"type":"string","enum":["linearComment","slack"]}}},"required":["updates"]},"entityFlagUpdate":{"description":"Update for a single flag's explicit targeting override","type":"object","properties":{"flagKey":{"$ref":"#/components/schemas/flagKey"},"specificTargetValue":{"description":"Set to true to add a specific-targeting override, or null to remove it","anyOf":[{"type":"boolean","const":true},{"type":"null"}]}},"required":["flagKey","specificTargetValue"]},"flagKey":{"description":"Unique flag key","type":"string","minLength":1},"updateEntityFlagsResponse":{"description":"Updated entity flags and the environment flag-state version containing the change","type":"object","properties":{"data":{"description":"List of flags with their enabled status","type":"array","items":{"$ref":"#/components/schemas/entityFlag"}},"totalCount":{"description":"Total number of flags","type":"integer"},"pageSize":{"description":"Page size","type":"integer"},"pageIndex":{"description":"Page index","type":"integer"},"flagStateVersion":{"$ref":"#/components/schemas/flagStateVersion"}},"required":["data","totalCount","pageSize","pageIndex","flagStateVersion"],"additionalProperties":false},"entityFlag":{"description":"Flag information with enabled status for an entity","type":"object","properties":{"id":{"$ref":"#/components/schemas/flagId"},"key":{"$ref":"#/components/schemas/flagKey"},"name":{"description":"Flag name","type":"string","minLength":1,"maxLength":255},"createdAt":{"description":"Timestamp when the flag was created","type":"string"},"value":{"description":"Whether the flag is enabled for this entity","type":"boolean"},"specificTargetValue":{"description":"Value if directly added via specific targets, null if not specifically targeted","anyOf":[{"type":"boolean"},{"type":"null"}]},"firstExposureAt":{"description":"First time the entity was exposed to this flag","anyOf":[{"type":"string"},{"type":"null"}]},"lastExposureAt":{"description":"Last time the entity was exposed to this flag","anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckAt":{"description":"Last time the flag was checked for this entity","anyOf":[{"type":"string"},{"type":"null"}]},"exposureCount":{"description":"Number of times the entity was exposed to this flag","type":"integer"},"firstTrackAt":{"description":"First time a track event was recorded for this flag","anyOf":[{"type":"string"},{"type":"null"}]},"lastTrackAt":{"description":"Last time a track event was recorded for this flag","anyOf":[{"type":"string"},{"type":"null"}]},"trackCount":{"description":"Number of track events for this flag","type":"integer"}},"required":["id","key","name","createdAt","value","specificTargetValue","firstExposureAt","lastExposureAt","lastCheckAt","exposureCount","firstTrackAt","lastTrackAt","trackCount"],"additionalProperties":false},"flagId":{"description":"Flag ID","type":"string","minLength":1},"flagStateVersion":{"description":"Environment flag-state version containing the completed mutation","type":"integer","minimum":0},"ErrorResponse":{"description":"The error response, including individual issues, if applicable","type":"object","properties":{"error":{"description":"The error","type":"object","properties":{"code":{"description":"Error code","type":"string","enum":["invalid_request","not_found","not_possible","not_allowed","not_available","unknown_error","unauthorized","unauthenticated"]},"message":{"description":"Human readable error message","type":"string"}},"required":["code","message"],"additionalProperties":false},"issues":{"description":"Individual validation issues, if applicable","type":"object","propertyNames":{"description":"The field that has the issue (uses dot notation). Empty string if the issue is at the root.","type":"string"},"additionalProperties":{"description":"Error messages for this field","type":"array","items":{"description":"The error message","type":"string"}}}},"required":["error"],"additionalProperties":false}}},"paths":{"/apps/{appId}/envs/{envId}/companies/{companyId}/flags":{"patch":{"summary":"Update flag targeting for a company","description":"Update specific targeting for flags for a company in an environment. Returns the environment flag-state version containing the completed update.","operationId":"updateCompanyFlags","parameters":[{"in":"path","name":"appId","schema":{"$ref":"#/components/schemas/appId"},"required":true,"description":"App identifier"},{"in":"path","name":"envId","schema":{"$ref":"#/components/schemas/envId"},"required":true,"description":"Environment identifier"},{"in":"path","name":"companyId","schema":{"$ref":"#/components/schemas/companyId"},"required":true,"description":"Company ID within your application"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/updateEntityFlagsBody"}}}},"responses":{"200":{"description":"Requested resource retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/updateEntityFlagsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource, or its parent, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get flags for a user

> Retrieve all flags with their targeting status for a specific user

```json
{"openapi":"3.1.0","info":{"title":"Reflag Management API","version":"3.1.0"},"servers":[{"url":"https://app.reflag.com/api","description":"Production server"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"bearer","description":"API key authentication, for service access"}},"schemas":{"appId":{"description":"App identifier","type":"string","minLength":1},"envId":{"description":"Environment identifier","type":"string","minLength":1},"userId":{"description":"User ID within your application","type":"string","minLength":1,"maxLength":128},"entityFlagsResponse":{"description":"Response containing flags for an entity","type":"object","properties":{"data":{"description":"List of flags with their enabled status","type":"array","items":{"$ref":"#/components/schemas/entityFlag"}},"totalCount":{"description":"Total number of flags","type":"integer"},"pageSize":{"description":"Page size","type":"integer"},"pageIndex":{"description":"Page index","type":"integer"}},"required":["data","totalCount","pageSize","pageIndex"],"additionalProperties":false},"entityFlag":{"description":"Flag information with enabled status for an entity","type":"object","properties":{"id":{"$ref":"#/components/schemas/flagId"},"key":{"$ref":"#/components/schemas/flagKey"},"name":{"description":"Flag name","type":"string","minLength":1,"maxLength":255},"createdAt":{"description":"Timestamp when the flag was created","type":"string"},"value":{"description":"Whether the flag is enabled for this entity","type":"boolean"},"specificTargetValue":{"description":"Value if directly added via specific targets, null if not specifically targeted","anyOf":[{"type":"boolean"},{"type":"null"}]},"firstExposureAt":{"description":"First time the entity was exposed to this flag","anyOf":[{"type":"string"},{"type":"null"}]},"lastExposureAt":{"description":"Last time the entity was exposed to this flag","anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckAt":{"description":"Last time the flag was checked for this entity","anyOf":[{"type":"string"},{"type":"null"}]},"exposureCount":{"description":"Number of times the entity was exposed to this flag","type":"integer"},"firstTrackAt":{"description":"First time a track event was recorded for this flag","anyOf":[{"type":"string"},{"type":"null"}]},"lastTrackAt":{"description":"Last time a track event was recorded for this flag","anyOf":[{"type":"string"},{"type":"null"}]},"trackCount":{"description":"Number of track events for this flag","type":"integer"}},"required":["id","key","name","createdAt","value","specificTargetValue","firstExposureAt","lastExposureAt","lastCheckAt","exposureCount","firstTrackAt","lastTrackAt","trackCount"],"additionalProperties":false},"flagId":{"description":"Flag ID","type":"string","minLength":1},"flagKey":{"description":"Unique flag key","type":"string","minLength":1},"ErrorResponse":{"description":"The error response, including individual issues, if applicable","type":"object","properties":{"error":{"description":"The error","type":"object","properties":{"code":{"description":"Error code","type":"string","enum":["invalid_request","not_found","not_possible","not_allowed","not_available","unknown_error","unauthorized","unauthenticated"]},"message":{"description":"Human readable error message","type":"string"}},"required":["code","message"],"additionalProperties":false},"issues":{"description":"Individual validation issues, if applicable","type":"object","propertyNames":{"description":"The field that has the issue (uses dot notation). Empty string if the issue is at the root.","type":"string"},"additionalProperties":{"description":"Error messages for this field","type":"array","items":{"description":"The error message","type":"string"}}}},"required":["error"],"additionalProperties":false}}},"paths":{"/apps/{appId}/envs/{envId}/users/{userId}/flags":{"get":{"summary":"Get flags for a user","description":"Retrieve all flags with their targeting status for a specific user","operationId":"getUserFlags","parameters":[{"in":"path","name":"appId","schema":{"$ref":"#/components/schemas/appId"},"required":true,"description":"App identifier"},{"in":"path","name":"envId","schema":{"$ref":"#/components/schemas/envId"},"required":true,"description":"Environment identifier"},{"in":"path","name":"userId","schema":{"$ref":"#/components/schemas/userId"},"required":true,"description":"User ID within your application"}],"responses":{"200":{"description":"Requested resource retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/entityFlagsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource, or its parent, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Update flag targeting for a user

> Update specific targeting for flags for a user in an environment. Returns the environment flag-state version containing the completed update.

```json
{"openapi":"3.1.0","info":{"title":"Reflag Management API","version":"3.1.0"},"servers":[{"url":"https://app.reflag.com/api","description":"Production server"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"bearer","description":"API key authentication, for service access"}},"schemas":{"appId":{"description":"App identifier","type":"string","minLength":1},"envId":{"description":"Environment identifier","type":"string","minLength":1},"userId":{"description":"User ID within your application","type":"string","minLength":1,"maxLength":128},"updateEntityFlagsBody":{"description":"Request body for updating flags for an entity","type":"object","properties":{"updates":{"description":"List of flag updates to apply","minItems":1,"type":"array","items":{"$ref":"#/components/schemas/entityFlagUpdate"}},"changeDescription":{"description":"Description of the change for audit history","type":"string"},"notifications":{"description":"Destination list for notifications about the change. Use [] to disable notifications. Omit to use configured defaults.","type":"array","items":{"type":"string","enum":["linearComment","slack"]}}},"required":["updates"]},"entityFlagUpdate":{"description":"Update for a single flag's explicit targeting override","type":"object","properties":{"flagKey":{"$ref":"#/components/schemas/flagKey"},"specificTargetValue":{"description":"Set to true to add a specific-targeting override, or null to remove it","anyOf":[{"type":"boolean","const":true},{"type":"null"}]}},"required":["flagKey","specificTargetValue"]},"flagKey":{"description":"Unique flag key","type":"string","minLength":1},"updateEntityFlagsResponse":{"description":"Updated entity flags and the environment flag-state version containing the change","type":"object","properties":{"data":{"description":"List of flags with their enabled status","type":"array","items":{"$ref":"#/components/schemas/entityFlag"}},"totalCount":{"description":"Total number of flags","type":"integer"},"pageSize":{"description":"Page size","type":"integer"},"pageIndex":{"description":"Page index","type":"integer"},"flagStateVersion":{"$ref":"#/components/schemas/flagStateVersion"}},"required":["data","totalCount","pageSize","pageIndex","flagStateVersion"],"additionalProperties":false},"entityFlag":{"description":"Flag information with enabled status for an entity","type":"object","properties":{"id":{"$ref":"#/components/schemas/flagId"},"key":{"$ref":"#/components/schemas/flagKey"},"name":{"description":"Flag name","type":"string","minLength":1,"maxLength":255},"createdAt":{"description":"Timestamp when the flag was created","type":"string"},"value":{"description":"Whether the flag is enabled for this entity","type":"boolean"},"specificTargetValue":{"description":"Value if directly added via specific targets, null if not specifically targeted","anyOf":[{"type":"boolean"},{"type":"null"}]},"firstExposureAt":{"description":"First time the entity was exposed to this flag","anyOf":[{"type":"string"},{"type":"null"}]},"lastExposureAt":{"description":"Last time the entity was exposed to this flag","anyOf":[{"type":"string"},{"type":"null"}]},"lastCheckAt":{"description":"Last time the flag was checked for this entity","anyOf":[{"type":"string"},{"type":"null"}]},"exposureCount":{"description":"Number of times the entity was exposed to this flag","type":"integer"},"firstTrackAt":{"description":"First time a track event was recorded for this flag","anyOf":[{"type":"string"},{"type":"null"}]},"lastTrackAt":{"description":"Last time a track event was recorded for this flag","anyOf":[{"type":"string"},{"type":"null"}]},"trackCount":{"description":"Number of track events for this flag","type":"integer"}},"required":["id","key","name","createdAt","value","specificTargetValue","firstExposureAt","lastExposureAt","lastCheckAt","exposureCount","firstTrackAt","lastTrackAt","trackCount"],"additionalProperties":false},"flagId":{"description":"Flag ID","type":"string","minLength":1},"flagStateVersion":{"description":"Environment flag-state version containing the completed mutation","type":"integer","minimum":0},"ErrorResponse":{"description":"The error response, including individual issues, if applicable","type":"object","properties":{"error":{"description":"The error","type":"object","properties":{"code":{"description":"Error code","type":"string","enum":["invalid_request","not_found","not_possible","not_allowed","not_available","unknown_error","unauthorized","unauthenticated"]},"message":{"description":"Human readable error message","type":"string"}},"required":["code","message"],"additionalProperties":false},"issues":{"description":"Individual validation issues, if applicable","type":"object","propertyNames":{"description":"The field that has the issue (uses dot notation). Empty string if the issue is at the root.","type":"string"},"additionalProperties":{"description":"Error messages for this field","type":"array","items":{"description":"The error message","type":"string"}}}},"required":["error"],"additionalProperties":false}}},"paths":{"/apps/{appId}/envs/{envId}/users/{userId}/flags":{"patch":{"summary":"Update flag targeting for a user","description":"Update specific targeting for flags for a user in an environment. Returns the environment flag-state version containing the completed update.","operationId":"updateUserFlags","parameters":[{"in":"path","name":"appId","schema":{"$ref":"#/components/schemas/appId"},"required":true,"description":"App identifier"},{"in":"path","name":"envId","schema":{"$ref":"#/components/schemas/envId"},"required":true,"description":"Environment identifier"},{"in":"path","name":"userId","schema":{"$ref":"#/components/schemas/userId"},"required":true,"description":"User ID within your application"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/updateEntityFlagsBody"}}}},"responses":{"200":{"description":"Requested resource retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/updateEntityFlagsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource, or its parent, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get flag targeting for an environment

> Retrieve targeting for a flag in an environment

```json
{"openapi":"3.1.0","info":{"title":"Reflag Management API","version":"3.1.0"},"servers":[{"url":"https://app.reflag.com/api","description":"Production server"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"bearer","description":"API key authentication, for service access"}},"schemas":{"appId":{"description":"App identifier","type":"string","minLength":1},"flagKey":{"description":"Unique flag key","type":"string","minLength":1},"envId":{"description":"Environment identifier","type":"string","minLength":1},"flagTargeting":{"description":"Flag targeting information and its audience","type":"object","properties":{"flagKey":{"$ref":"#/components/schemas/flagKey"},"version":{"$ref":"#/components/schemas/flagVersion"},"updatedAt":{"description":"Last time the targeting was updated","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"specificTargets":{"description":"The flag targeting for each value","type":"object","propertyNames":{"$ref":"#/components/schemas/flagValue"},"additionalProperties":{"$ref":"#/components/schemas/flagValueTargeting"}}},"required":["flagKey","version","updatedAt","specificTargets"],"additionalProperties":false},"flagVersion":{"description":"Flag targeting version","type":"integer"},"flagValue":{"description":"The value of the flag served to the audience.","type":"string","const":"true"},"flagValueTargeting":{"description":"Flag targeting value and its audience","type":"object","properties":{"companyIds":{"description":"Companies that were explicitly given the value","type":"array","items":{"$ref":"#/components/schemas/companyId"}},"userIds":{"description":"Users that were explicitly given the value","type":"array","items":{"$ref":"#/components/schemas/userId"}}},"required":["companyIds","userIds"],"additionalProperties":false},"companyId":{"description":"Company ID within your application","type":"string","minLength":1,"maxLength":128},"userId":{"description":"User ID within your application","type":"string","minLength":1,"maxLength":128},"ErrorResponse":{"description":"The error response, including individual issues, if applicable","type":"object","properties":{"error":{"description":"The error","type":"object","properties":{"code":{"description":"Error code","type":"string","enum":["invalid_request","not_found","not_possible","not_allowed","not_available","unknown_error","unauthorized","unauthenticated"]},"message":{"description":"Human readable error message","type":"string"}},"required":["code","message"],"additionalProperties":false},"issues":{"description":"Individual validation issues, if applicable","type":"object","propertyNames":{"description":"The field that has the issue (uses dot notation). Empty string if the issue is at the root.","type":"string"},"additionalProperties":{"description":"Error messages for this field","type":"array","items":{"description":"The error message","type":"string"}}}},"required":["error"],"additionalProperties":false}}},"paths":{"/apps/{appId}/flags/{flagKey}/targeting/{envId}":{"get":{"summary":"Get flag targeting for an environment","description":"Retrieve targeting for a flag in an environment","operationId":"getFlagTargeting","parameters":[{"in":"path","name":"appId","schema":{"$ref":"#/components/schemas/appId"},"required":true,"description":"App identifier"},{"in":"path","name":"flagKey","schema":{"$ref":"#/components/schemas/flagKey"},"required":true,"description":"Unique flag key"},{"in":"path","name":"envId","schema":{"$ref":"#/components/schemas/envId"},"required":true,"description":"Environment identifier"}],"responses":{"200":{"description":"Requested resource retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/flagTargeting"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource, or its parent, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create or update a company

> Synchronously create or update a company in an environment. Requires the \`write:entities\` API key scope or admin member access. This scope also grants deletion through the corresponding entity DELETE endpoints, but does not grant membership changes or flag targeting; grant \`write:flag:targeting\` separately to assign flags and \`read\` for GET requests. Attributes accept JSON values and are normalized and merged using the same rules as ingestion. Recognized name and avatar attributes also update the corresponding company fields; top-level \`name\` takes precedence over name attributes. Omitting a field preserves its existing value. New companies may omit all fields. When this request succeeds, a subsequent company targeting request can read the company. Flag configuration propagation to SDKs is independent. Delayed ingestion writes may later replace overlapping values because the last database writer wins.

```json
{"openapi":"3.1.0","info":{"title":"Reflag Management API","version":"3.1.0"},"servers":[{"url":"https://app.reflag.com/api","description":"Production server"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"bearer","description":"API key authentication, for service access"}},"schemas":{"appId":{"description":"App identifier","type":"string","minLength":1},"envId":{"description":"Environment identifier","type":"string","minLength":1},"companyId":{"description":"Company ID within your application","type":"string","minLength":1,"maxLength":128},"entityAttributesInput":{"description":"Entity attributes. Values are normalized exactly like ingestion before being merged with existing attributes.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/components/schemas/__schema0"}},{"type":"null"}]},"__schema0":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/components/schemas/__schema0"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/components/schemas/__schema0"}}]},"entityAttributesInputOutput":{"description":"Entity attributes. Values are normalized exactly like ingestion before being merged with existing attributes.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/components/schemas/__schema1"}},{"type":"null"}]},"__schema1":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/components/schemas/__schema1"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/components/schemas/__schema1"}}]},"ErrorResponse":{"description":"The error response, including individual issues, if applicable","type":"object","properties":{"error":{"description":"The error","type":"object","properties":{"code":{"description":"Error code","type":"string","enum":["invalid_request","not_found","not_possible","not_allowed","not_available","unknown_error","unauthorized","unauthenticated"]},"message":{"description":"Human readable error message","type":"string"}},"required":["code","message"],"additionalProperties":false},"issues":{"description":"Individual validation issues, if applicable","type":"object","propertyNames":{"description":"The field that has the issue (uses dot notation). Empty string if the issue is at the root.","type":"string"},"additionalProperties":{"description":"Error messages for this field","type":"array","items":{"description":"The error message","type":"string"}}}},"required":["error"],"additionalProperties":false}}},"paths":{"/apps/{appId}/envs/{envId}/companies/{companyId}":{"put":{"summary":"Create or update a company","description":"Synchronously create or update a company in an environment. Requires the `write:entities` API key scope or admin member access. This scope also grants deletion through the corresponding entity DELETE endpoints, but does not grant membership changes or flag targeting; grant `write:flag:targeting` separately to assign flags and `read` for GET requests. Attributes accept JSON values and are normalized and merged using the same rules as ingestion. Recognized name and avatar attributes also update the corresponding company fields; top-level `name` takes precedence over name attributes. Omitting a field preserves its existing value. New companies may omit all fields. When this request succeeds, a subsequent company targeting request can read the company. Flag configuration propagation to SDKs is independent. Delayed ingestion writes may later replace overlapping values because the last database writer wins.","operationId":"upsertCompany","parameters":[{"in":"path","name":"appId","schema":{"$ref":"#/components/schemas/appId"},"required":true,"description":"App identifier"},{"in":"path","name":"envId","schema":{"$ref":"#/components/schemas/envId"},"required":true,"description":"Environment identifier"},{"in":"path","name":"companyId","schema":{"$ref":"#/components/schemas/companyId"},"required":true,"description":"Company ID within your application"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"Company name. Omit it to preserve an existing name; new companies may be unnamed.","type":"string","minLength":1,"maxLength":128},"attributes":{"$ref":"#/components/schemas/entityAttributesInput"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Company created or updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"Company name. Omit it to preserve an existing name; new companies may be unnamed.","type":"string","minLength":1,"maxLength":128},"attributes":{"$ref":"#/components/schemas/entityAttributesInputOutput"},"id":{"$ref":"#/components/schemas/companyId"}},"required":["id"],"additionalProperties":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource, or its parent, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Delete a company

> Synchronously delete a company and its related data from an environment. Requires the \`write:entities\` API key scope or admin member access. By default, users that belong only to this company are also deleted; set \`deleteUsers\` to false to preserve them. Users that belong to other companies are always preserved.

```json
{"openapi":"3.1.0","info":{"title":"Reflag Management API","version":"3.1.0"},"servers":[{"url":"https://app.reflag.com/api","description":"Production server"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"bearer","description":"API key authentication, for service access"}},"schemas":{"appId":{"description":"App identifier","type":"string","minLength":1},"envId":{"description":"Environment identifier","type":"string","minLength":1},"companyId":{"description":"Company ID within your application","type":"string","minLength":1,"maxLength":128},"ErrorResponse":{"description":"The error response, including individual issues, if applicable","type":"object","properties":{"error":{"description":"The error","type":"object","properties":{"code":{"description":"Error code","type":"string","enum":["invalid_request","not_found","not_possible","not_allowed","not_available","unknown_error","unauthorized","unauthenticated"]},"message":{"description":"Human readable error message","type":"string"}},"required":["code","message"],"additionalProperties":false},"issues":{"description":"Individual validation issues, if applicable","type":"object","propertyNames":{"description":"The field that has the issue (uses dot notation). Empty string if the issue is at the root.","type":"string"},"additionalProperties":{"description":"Error messages for this field","type":"array","items":{"description":"The error message","type":"string"}}}},"required":["error"],"additionalProperties":false}}},"paths":{"/apps/{appId}/envs/{envId}/companies/{companyId}":{"delete":{"summary":"Delete a company","description":"Synchronously delete a company and its related data from an environment. Requires the `write:entities` API key scope or admin member access. By default, users that belong only to this company are also deleted; set `deleteUsers` to false to preserve them. Users that belong to other companies are always preserved.","operationId":"deleteCompany","parameters":[{"in":"path","name":"appId","schema":{"$ref":"#/components/schemas/appId"},"required":true,"description":"App identifier"},{"in":"path","name":"envId","schema":{"$ref":"#/components/schemas/envId"},"required":true,"description":"Environment identifier"},{"in":"path","name":"companyId","schema":{"$ref":"#/components/schemas/companyId"},"required":true,"description":"Company ID within your application"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"deleteUsers":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Company deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource, or its parent, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create or update a user

> Synchronously create or update a user in an environment. Requires the \`write:entities\` API key scope or admin member access. This scope also grants deletion through the corresponding entity DELETE endpoints, but does not grant membership changes or flag targeting; grant \`write:flag:targeting\` separately to assign flags and \`read\` for GET requests. Attributes accept JSON values and are normalized and merged using the same rules as ingestion. Recognized name, email, and avatar attributes also update the corresponding user fields; top-level \`name\` takes precedence over name attributes. Omitting a field preserves its existing value. New users may omit all fields. When this request succeeds, a subsequent user targeting request can read the user. Flag configuration propagation to SDKs is independent. Delayed ingestion writes may later replace overlapping values because the last database writer wins.

```json
{"openapi":"3.1.0","info":{"title":"Reflag Management API","version":"3.1.0"},"servers":[{"url":"https://app.reflag.com/api","description":"Production server"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"bearer","description":"API key authentication, for service access"}},"schemas":{"appId":{"description":"App identifier","type":"string","minLength":1},"envId":{"description":"Environment identifier","type":"string","minLength":1},"userId":{"description":"User ID within your application","type":"string","minLength":1,"maxLength":128},"entityAttributesInput":{"description":"Entity attributes. Values are normalized exactly like ingestion before being merged with existing attributes.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/components/schemas/__schema0"}},{"type":"null"}]},"__schema0":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/components/schemas/__schema0"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/components/schemas/__schema0"}}]},"entityAttributesInputOutput":{"description":"Entity attributes. Values are normalized exactly like ingestion before being merged with existing attributes.","anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/components/schemas/__schema1"}},{"type":"null"}]},"__schema1":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/components/schemas/__schema1"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/components/schemas/__schema1"}}]},"ErrorResponse":{"description":"The error response, including individual issues, if applicable","type":"object","properties":{"error":{"description":"The error","type":"object","properties":{"code":{"description":"Error code","type":"string","enum":["invalid_request","not_found","not_possible","not_allowed","not_available","unknown_error","unauthorized","unauthenticated"]},"message":{"description":"Human readable error message","type":"string"}},"required":["code","message"],"additionalProperties":false},"issues":{"description":"Individual validation issues, if applicable","type":"object","propertyNames":{"description":"The field that has the issue (uses dot notation). Empty string if the issue is at the root.","type":"string"},"additionalProperties":{"description":"Error messages for this field","type":"array","items":{"description":"The error message","type":"string"}}}},"required":["error"],"additionalProperties":false}}},"paths":{"/apps/{appId}/envs/{envId}/users/{userId}":{"put":{"summary":"Create or update a user","description":"Synchronously create or update a user in an environment. Requires the `write:entities` API key scope or admin member access. This scope also grants deletion through the corresponding entity DELETE endpoints, but does not grant membership changes or flag targeting; grant `write:flag:targeting` separately to assign flags and `read` for GET requests. Attributes accept JSON values and are normalized and merged using the same rules as ingestion. Recognized name, email, and avatar attributes also update the corresponding user fields; top-level `name` takes precedence over name attributes. Omitting a field preserves its existing value. New users may omit all fields. When this request succeeds, a subsequent user targeting request can read the user. Flag configuration propagation to SDKs is independent. Delayed ingestion writes may later replace overlapping values because the last database writer wins.","operationId":"upsertUser","parameters":[{"in":"path","name":"appId","schema":{"$ref":"#/components/schemas/appId"},"required":true,"description":"App identifier"},{"in":"path","name":"envId","schema":{"$ref":"#/components/schemas/envId"},"required":true,"description":"Environment identifier"},{"in":"path","name":"userId","schema":{"$ref":"#/components/schemas/userId"},"required":true,"description":"User ID within your application"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"User name. Omit it to preserve an existing name; new users may be unnamed.","type":"string","minLength":1,"maxLength":128},"attributes":{"$ref":"#/components/schemas/entityAttributesInput"}},"additionalProperties":false}}}},"responses":{"200":{"description":"User created or updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"User name. Omit it to preserve an existing name; new users may be unnamed.","type":"string","minLength":1,"maxLength":128},"attributes":{"$ref":"#/components/schemas/entityAttributesInputOutput"},"id":{"$ref":"#/components/schemas/userId"}},"required":["id"],"additionalProperties":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource, or its parent, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Delete a user

> Synchronously delete a user and its related data, including company memberships, from an environment. Requires the \`write:entities\` API key scope or admin member access.

```json
{"openapi":"3.1.0","info":{"title":"Reflag Management API","version":"3.1.0"},"servers":[{"url":"https://app.reflag.com/api","description":"Production server"}],"security":[{"APIKey":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"bearer","description":"API key authentication, for service access"}},"schemas":{"appId":{"description":"App identifier","type":"string","minLength":1},"envId":{"description":"Environment identifier","type":"string","minLength":1},"userId":{"description":"User ID within your application","type":"string","minLength":1,"maxLength":128},"ErrorResponse":{"description":"The error response, including individual issues, if applicable","type":"object","properties":{"error":{"description":"The error","type":"object","properties":{"code":{"description":"Error code","type":"string","enum":["invalid_request","not_found","not_possible","not_allowed","not_available","unknown_error","unauthorized","unauthenticated"]},"message":{"description":"Human readable error message","type":"string"}},"required":["code","message"],"additionalProperties":false},"issues":{"description":"Individual validation issues, if applicable","type":"object","propertyNames":{"description":"The field that has the issue (uses dot notation). Empty string if the issue is at the root.","type":"string"},"additionalProperties":{"description":"Error messages for this field","type":"array","items":{"description":"The error message","type":"string"}}}},"required":["error"],"additionalProperties":false}}},"paths":{"/apps/{appId}/envs/{envId}/users/{userId}":{"delete":{"summary":"Delete a user","description":"Synchronously delete a user and its related data, including company memberships, from an environment. Requires the `write:entities` API key scope or admin member access.","operationId":"deleteUser","parameters":[{"in":"path","name":"appId","schema":{"$ref":"#/components/schemas/appId"},"required":true,"description":"App identifier"},{"in":"path","name":"envId","schema":{"$ref":"#/components/schemas/envId"},"required":true,"description":"Environment identifier"},{"in":"path","name":"userId","schema":{"$ref":"#/components/schemas/userId"},"required":true,"description":"User ID within your application"}],"responses":{"200":{"description":"User deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Requested resource, or its parent, not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.reflag.com/api/reflag-rest-api/reflag-api-reference.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.