기능 플래그 API

기능 플래그는 SDK가 각 디바이스에 대해 읽는 속성을 가진 원격 스위치입니다. 이 API는 애플리케이션의 플래그를 관리하며, Control Panel의 Audience → Feature Flags와 동일한 작업을 제공합니다. 웹사이트나 모바일 앱에서 플래그를 읽으려면 Web SDK, Android SDK 또는 iOS SDK를 사용하세요.

기본 URL

https://rpc-api.svc-nue.pushwoosh.com

모든 엔드포인트는 HTTPS를 통해 제공됩니다. 요청과 응답은 application/json을 사용합니다.

인증

모든 요청에는 서버 API 토큰이 포함된 Authorization 헤더가 있어야 합니다.

Authorization: Api YOUR_API_TOKEN

플래그를 읽으려면 애플리케이션에 대한 액세스 권한이 필요합니다. 플래그를 생성하고 변경하려면 애플리케이션을 관리할 권한이 필요합니다.

규칙

필드 이름 지정: 요청 본문은 lowerCamelCase 또는 snake_case를 허용합니다. 응답은 기능 플래그 객체와 같이 snake_case를 사용합니다.
백분율은 베이시스 포인트 단위입니다. percent_bp는 0부터 10000까지이며, 2000은 20%입니다.
버전: 모든 플래그에는 version이 있습니다. Update, SetRulePercent, Reshuffle은 마지막으로 읽은 버전을 받으며, 그 이후 플래그가 변경되었다면 VERSION_CONFLICT로 실패하므로 동시 편집이 서로를 덮어쓰지 않습니다. 플래그를 다시 읽고 재시도하세요.
상태: active, killed 또는 archived입니다. Kill, Unkill, Archive, Restore는 상태만 변경하며 버전을 받지 않습니다.

엔드포인트

각 REST 엔드포인트에는 동일한 매개변수를 사용하는 MCP 도구가 있습니다.

메서드	경로	설명	MCP 도구
`GET`	`/api/applications/{application_code}/feature_flags`	애플리케이션의 플래그 목록 조회	`list_feature_flags`
`GET`	`/api/applications/{application_code}/feature_flags/{key}`	플래그 하나 조회	`get_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags`	플래그 생성	`create_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}`	이름, 설명, 속성 및 규칙 교체	`update_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/rules/{rule_id}/percent`	규칙 하나의 롤아웃 비율 변경	`set_feature_flag_rule_percent`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/kill`	모든 사용자에 대해 플래그 끄기	`kill_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/unkill`	중지된 플래그 다시 켜기	`unkill_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/archive`	플래그 보관	`archive_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/restore`	보관된 플래그 복원	`restore_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/reshuffle`	새로운 사용자 샘플 선택	`reshuffle_feature_flag`
`GET`	`/api/applications/{application_code}/feature_flags/{key}/history`	플래그의 변경 내역 조회	`list_feature_flag_history`

List와 History를 제외한 모든 엔드포인트는 작업 후의 기능 플래그 객체인 { "flag": { ... } }를 반환합니다.

목록 조회

GET /api/applications/{application_code}/feature_flags

요청은 다음 매개변수를 받습니다.

매개변수	위치	타입	설명
`application_code`	path	string	애플리케이션 코드입니다.
`status`	query	string	선택 사항입니다. `active`, `killed` 또는 `archived`입니다. 모든 플래그를 조회하려면 생략하세요.

기능 플래그 객체의 배열인 { "flags": [ ... ] }를 반환합니다.

조회

GET /api/applications/{application_code}/feature_flags/{key}

속성, 규칙 및 현재 version과 함께 플래그 하나를 반환합니다.

생성

active 상태의 플래그를 생성합니다. 서버가 모든 규칙의 rule_id를 생성합니다.

POST /api/applications/{application_code}/feature_flags

요청 본문에는 다음 필드가 있습니다.

매개변수	타입	필수	설명
`key`	string	예	`^[A-Za-z0-9_.-]{1,58}$`와 일치해야 합니다. 보관된 플래그를 포함해 애플리케이션 내에서 고유하며, 대소문자를 구분하지 않고 비교합니다. 나중에 변경할 수 없습니다.
`name`	string	아니요	표시 이름이며 최대 255자입니다.
`description`	string	아니요	설명입니다.
`properties`	속성 객체의 배열	아니요	최대 50개의 속성입니다.
`defaults`	object	속성이 있는 경우 예	플래그가 꺼진 디바이스에 적용되는 각 속성의 값이며, 속성 키를 키로 사용합니다. 각 값은 속성 타입과 일치해야 합니다.
`rules`	규칙 객체의 배열	아니요	순서가 있는 규칙이며 최대 10개입니다. 세그먼트가 디바이스와 일치하는 첫 번째 규칙이 결과를 결정합니다.

요청 예시

{
  "key": "new_checkout",
  "name": "New checkout",
  "properties": [
    { "key": "button_color", "type": "string" },
    { "key": "show_apple_pay", "type": "boolean" }
  ],
  "defaults": { "button_color": "blue", "show_apple_pay": false },
  "rules": [
    {
      "name": "Beta testers",
      "filter_code": "XXXXX-XXXXX",
      "percent_bp": 10000,
      "overrides": { "button_color": "green", "show_apple_pay": true }
    },
    {
      "name": "Everyone else",
      "filter_code": "",
      "percent_bp": 2000,
      "overrides": { "button_color": "orange" }
    }
  ]
}

업데이트

플래그의 이름, 설명, 속성, 기본값 및 규칙을 교체합니다. 여기서는 상태가 절대 변경되지 않습니다. 변경된 필드만이 아니라 모든 필드를 보내세요.

POST /api/applications/{application_code}/feature_flags/{key}

key를 제외하고 생성과 동일한 본문에 마지막으로 읽은 version을 더해 받습니다. 기존 규칙의 rule_id는 모두 유지하세요. rule_id가 없는 규칙은 새 규칙으로 생성됩니다. 속성의 타입은 속성이 생성된 후에는 변경할 수 없습니다.

규칙 비율 설정

규칙 하나의 롤아웃 비율을 변경합니다. 비율이 늘어나도 이미 플래그를 받은 사용자는 그대로 유지합니다.

POST /api/applications/{application_code}/feature_flags/{key}/rules/{rule_id}/percent

{ "percentBp": 5000, "version": 3 }

Kill 및 Unkill

POST .../feature_flags/{key}/kill은 모든 디바이스에 대해 플래그를 끄며, 이후 디바이스는 기본 속성 값을 받습니다. 규칙과 속성은 유지됩니다.

POST .../feature_flags/{key}/unkill은 중지된 플래그를 기존 규칙 그대로 다시 켭니다.

두 요청 모두 빈 본문 {}을 받습니다.

보관 및 복원

POST .../feature_flags/{key}/archive는 디바이스로 플래그를 보내는 것을 중지합니다. 보관된 플래그는 요금제의 애플리케이션당 플래그 한도에 포함되지 않으며, 해당 키는 계속 예약된 상태로 남습니다.

POST .../feature_flags/{key}/restore는 보관된 플래그를 killed 상태로 되돌리므로 플래그가 저절로 켜지지 않습니다. 다시 롤아웃하려면 unkill을 호출하세요.

두 요청 모두 빈 본문 {}을 받습니다.

재셔플

모든 사용자를 새 버킷에 배치하여 동일한 비율로 다른 사용자 샘플이 선택되도록 합니다. 플래그가 켜져 있던 일부 사용자는 플래그를 잃고, 다른 사용자가 플래그를 받습니다.

POST /api/applications/{application_code}/feature_flags/{key}/reshuffle

{ "confirm": true, "version": 3 }

confirm은 true여야 합니다. 그렇지 않으면 요청이 CONFIRM_REQUIRED로 실패합니다.

변경 기록

플래그의 변경 내역을 최신순으로 반환합니다. 각 변경을 누가, 언제 했는지와 어떤 필드가 변경되었는지가 포함됩니다. Get과 마찬가지로 애플리케이션에 대한 접근 권한이 필요하며, 애플리케이션이나 플래그가 존재하지 않으면 404를 반환합니다.

GET /api/applications/{application_code}/feature_flags/{key}/history

요청은 다음 매개변수를 받습니다.

매개변수	위치	타입	설명
`application_code`	path	string	애플리케이션 코드입니다.
`key`	path	string	플래그 키입니다.
`page`	query	integer	선택 사항입니다. `0`부터 시작하는 페이지 번호입니다.
`per_page`	query	integer	선택 사항입니다. 페이지당 항목 수이며, 기본값은 `20`, 최대 `100`입니다.

{ "entries": [ ... ], "total": N }를 반환하며, total은 전체 페이지의 항목 수입니다. 각 항목에는 다음 필드가 있습니다.

필드	타입	설명
`version`	integer	이 변경으로 생성된 플래그 버전입니다.
`action`	string	`create`, `update`, `set_percent`, `kill`, `unkill`, `archive`, `restore` 또는 `reshuffle`입니다.
`user_id`	string	변경을 수행한 Control Panel 사용자의 ID입니다. API 토큰으로 이루어졌거나 Pushwoosh 서비스가 수행한 변경의 경우 `0`입니다.
`user_email`	string	해당 사용자의 이메일입니다. 사용자가 삭제되었거나 `user_id`가 `0`이면 비어 있습니다.
`by_api_token`	boolean	변경이 API 토큰으로 이루어졌으면 `true`입니다. 사용자나 Pushwoosh 서비스가 수행한 변경이면 `false`입니다.
`api_token_name`	string	변경 시점의 API 토큰 이름입니다. 토큰이 삭제된 후에도 유지됩니다. 토큰에 이름이 없거나 `by_api_token`이 `false`이면 비어 있습니다.
`created`	string	변경 시간이며 RFC 3339 형식입니다.
`flag`	기능 플래그 객체	변경 후의 플래그입니다.
`changes`	array	이전 버전과 달라진 필드입니다. `create`와 `reshuffle`의 경우, 그리고 기록이 시작되기 전에 생성된 플래그의 가장 오래된 항목의 경우 비교할 이전 버전이 없으므로 비어 있습니다.

changes의 각 항목에는 field, before, after가 있습니다. before와 after는 값을 JSON 문자열로 인코딩해 담으므로 문자열 값은 따옴표로 묶여 있습니다. field는 다음 값을 가집니다.

`field`	변경된 내용
`name`, `description`, `status`	이 이름을 가진 플래그 필드입니다.
`properties`	속성과 해당 기본값입니다.
`rules[<rule_id>]`	하나의 규칙입니다. 추가된 규칙의 경우 `before`가 비어 있습니다. 삭제된 규칙의 경우 `after`가 비어 있습니다.
`rules.order`	규칙의 순서입니다.

응답 예시

{
  "entries": [
    {
      "version": 4,
      "action": "set_percent",
      "user_id": "12345",
      "user_email": "owner@example.com",
      "by_api_token": false,
      "api_token_name": "",
      "created": "2026-10-14T09:30:00Z",
      "flag": { "key": "new_checkout", "status": "active", "version": 4 },
      "changes": [
        {
          "field": "rules[r_1a2b3c4d]",
          "before": "{\"rule_id\":\"r_1a2b3c4d\",\"name\":\"Beta testers\",\"filter_code\":\"XXXXX-XXXXX\",\"percent_bp\":2000,\"overrides\":{\"button_color\":\"green\"}}",
          "after": "{\"rule_id\":\"r_1a2b3c4d\",\"name\":\"Beta testers\",\"filter_code\":\"XXXXX-XXXXX\",\"percent_bp\":5000,\"overrides\":{\"button_color\":\"green\"}}"
        }
      ]
    }
  ],
  "total": 4
}

예시의 flag 객체는 축약되어 있습니다. 기록은 2026년 10월 13일 이후의 변경부터 저장됩니다. 기록된 변경이 없는 플래그는 항목을 반환하지 않습니다.

디바이스용 플래그 읽기

SDK는 별도의 엔드포인트에서 플래그를 읽습니다. Web SDK, Android SDK 또는 iOS SDK를 사용하는 경우 이 엔드포인트를 호출하지 않아도 됩니다. SDK가 호스트를 선택하고 응답을 직접 캐시하기 때문입니다.

POST https://api.pushwoosh.com/api/v2/device-api/getFeatureFlags

요청 본문에는 다음 필드가 있습니다.

필드	타입	설명
`application`	string	애플리케이션 코드입니다.
`hwid`	string	디바이스의 HWID입니다.
`etag`	string	선택 사항입니다. 디바이스가 보유한 마지막 응답의 `etag`입니다.

응답에는 다음 필드가 있습니다.

필드	타입	설명
`flags`	object	플래그 키를 키로 하는 플래그입니다. 각 플래그에는 `enabled`, `rule_id`, `properties`가 있습니다. 일치하는 규칙이 없으면 `rule_id`는 `default`이고, 중지된 플래그의 경우 비어 있습니다. 보관된 플래그는 포함되지 않습니다.
`etag`	string	다음 요청에 함께 보내세요.
`not_modified`	boolean	보낸 `etag`가 최신이면 `true`입니다. 이 경우 `flags`가 생략되고 디바이스는 보유한 사본을 유지합니다.
`partial`	boolean	디바이스의 세그먼트가 제시간에 매칭되지 않았으면 `true`입니다. 이 응답은 캐시하지 마세요.

기능 플래그가 포함되지 않은 요금제에서는 응답이 비어 있습니다.

객체

기능 플래그 객체

모든 엔드포인트는 다음 형태로 플래그를 반환합니다.

필드	타입	설명
`application_code`	string	플래그가 속한 애플리케이션입니다.
`key`	string	플래그 키입니다.
`name`	string	표시 이름입니다.
`description`	string	설명입니다.
`status`	string	`active`, `killed` 또는 `archived`입니다.
`properties`	속성 객체의 배열	플래그의 속성입니다.
`defaults`	object	플래그가 꺼진 디바이스에 적용되는 각 속성의 값입니다.
`rules`	규칙 객체의 배열	순서가 있는 규칙입니다.
`version`	integer	`Update`, `SetRulePercent`, `Reshuffle`에 다시 전달하세요.
`created`	string	생성 시간이며 RFC 3339 형식입니다.
`updated`	string	마지막 변경 시간이며 RFC 3339 형식입니다.
`last_modified_by_user_id`	string	플래그를 마지막으로 변경한 Control Panel 사용자입니다. 마지막 변경이 API 토큰으로 이루어졌거나 Pushwoosh 서비스가 수행한 경우 `0`입니다.

속성 객체

속성은 SDK가 플래그에서 읽는 하나의 값을 설명합니다.

필드	타입	설명
`key`	string	`^[A-Za-z0-9_]{1,64}$`와 일치해야 하며 플래그 내에서 고유합니다.
`type`	string	`string`, `number`, `boolean` 또는 `json`입니다. 속성이 생성된 후에는 변경할 수 없습니다.

규칙 객체

규칙은 누구에게 어떤 값으로 플래그를 켤지 결정합니다.

필드	타입	설명
`rule_id`	string	서버가 생성하며 `r_` 뒤에 16진수 8자리가 붙는 형식이고, 업데이트 간에 변하지 않습니다. 새 규칙에는 비워 두세요.
`name`	string	규칙 이름입니다.
`filter_code`	string	디바이스가 일치해야 하는 세그먼트입니다. 비어 있으면 모든 디바이스와 일치합니다. 세그먼트에는 태그, 위치, 애플리케이션 및 목록 조건만 포함할 수 있습니다.
`percent_bp`	integer	일치하는 사용자 중 플래그가 켜지는 비율이며 `0`–`10000`입니다. 세그먼트와 일치하는 디바이스는 비율 밖에 있더라도 이 규칙에서 멈춥니다.
`overrides`	object	이 규칙이 플래그를 켜는 디바이스에 대해 기본값을 대체하는 속성 값이며, 속성 키를 키로 사용합니다.

오류

거부된 요청은 다음 HTTP 상태 코드 중 하나를 반환합니다.

HTTP 상태	의미
`400 Bad Request`	요청이 유효하지 않거나(`field_violations`) 플래그 상태 또는 요금제가 요청을 허용하지 않습니다(`Type`). 아래의 본문 형식과 사유를 참조하세요.
`401 Unauthorized`	`Authorization` 헤더가 없거나 토큰이 유효하지 않습니다.
`403 Forbidden`	토큰이 애플리케이션을 관리할 수 없거나 애플리케이션이 시스템 애플리케이션입니다.
`404 Not Found`	애플리케이션 또는 플래그가 존재하지 않습니다.
`409 Conflict`	다른 요청이 현재 동일한 플래그를 변경하고 있습니다. 요청을 다시 시도하세요.
`500 Internal Server Error`	예기치 않은 서버 오류입니다. 본문은 `{"message": "Sorry, an unexpected error occurred"}`입니다.

유효하지 않은 요청은 필드 위반 목록과 함께 400을 반환합니다. 각 위반은 필드, 사유 및 사유의 인수를 나타냅니다.

{
  "code": 3,
  "message": "validation failed",
  "details": [
    {
      "@type": "type.googleapis.com/pushwoosh.rpc.errors.v3.BadRequest",
      "field_violations": [
        {
          "field": "key",
          "description": "a feature flag with this key already exists in the application",
          "reason": "KEY_TAKEN",
          "args": { "key": "new_checkout" }
        }
      ]
    }
  ]
}

플래그 상태 또는 요금제가 허용하지 않는 요청은 실패한 전제 조건 하나와 함께 400을 반환합니다. Type 및 Description 필드는 대문자로 시작합니다.

{
  "code": 9,
  "message": "precondition failed",
  "details": [
    {
      "@type": "type.googleapis.com/pushwoosh.rpc.errors.v3.FailedPrecondition",
      "Type": "VERSION_CONFLICT",
      "Description": "feature flag was changed: version 3 was sent, the current one is 4"
    }
  ]
}

필드 위반의 reason과 실패한 전제 조건의 Type은 다음 값을 가집니다.

사유	원인
`KEY_INVALID`	키가 `^[A-Za-z0-9_.-]{1,58}$`와 일치하지 않습니다.
`KEY_TAKEN`	보관된 플래그를 포함해 애플리케이션의 다른 플래그가 이 키를 사용하고 있습니다.
`TEXT_INVALID`	이름 또는 설명이 너무 길거나 금지된 문자가 포함되어 있습니다.
`PROPERTIES_LIMIT`	속성이 50개를 초과합니다.
`PROPERTY_KEY_INVALID`	속성 키가 유효하지 않거나 중복되었습니다.
`PROPERTY_TYPE_INVALID`	속성 타입이 `string`, `number`, `boolean`, `json` 중 하나가 아닙니다.
`PROPERTY_TYPE_IMMUTABLE`	요청이 기존 속성의 타입을 변경합니다.
`VALUE_INVALID`	기본값 또는 재정의 값이 없거나, 속성 타입과 일치하지 않거나, 5단계보다 깊게 중첩되어 있습니다.
`PROPERTIES_TOO_LARGE`	플래그의 속성 값이 10,000바이트를 초과합니다.
`RULES_LIMIT`	규칙이 10개를 초과합니다.
`RULE_NOT_FOUND`	`rule_id`가 플래그의 규칙에 속하지 않습니다.
`PERCENT_INVALID`	`percent_bp`가 `0`–`10000` 범위를 벗어났습니다.
`OVERRIDE_UNKNOWN_PROPERTY`	재정의가 플래그에 없는 속성을 지정합니다.
`SEGMENT_NOT_FOUND`	규칙 세그먼트가 존재하지 않거나 다른 애플리케이션에 속합니다.
`INVALID_SEGMENT_TYPE`	규칙 세그먼트에 플래그가 평가할 수 없는 조건(이벤트, 정적, 외부, 마지막 업데이트 또는 최적 발송 시간)이 있습니다.
`FLAG_DEPENDENCY`	규칙 세그먼트에 기능 플래그 조건이 있으며, 플래그는 다른 플래그에 의존할 수 없습니다. `Create`, `Update`, `Restore`가 반환하며, `filter_code`에 세그먼트 코드가 포함됩니다.
`CONFIRM_REQUIRED`	`confirm: true` 없이 `Reshuffle`을 보냈습니다.
`TAG_CONFLICT`	계정에 `PW_FF_` 뒤에 플래그 키가 붙은 이름의 사용자 지정 태그가 있습니다.
`FEATURE_FLAGS_NOT_ALLOWED`	계정의 요금제에 기능 플래그가 포함되어 있지 않습니다.
`FLAGS_LIMIT`	애플리케이션의 보관되지 않은 플래그 수가 요금제 허용 한도에 도달했습니다.
`VERSION_CONFLICT`	보낸 `version` 이후 플래그가 변경되었습니다.
`PAYLOAD_TOO_LARGE`	애플리케이션의 플래그가 한 디바이스에 대한 응답에서 64KB를 초과하게 됩니다.
`STATUS_CONFLICT`	상태가 작업을 허용하지 않습니다. 예를 들어 보관된 플래그를 중지하는 경우입니다.