API de feature flags

Uma feature flag é um interruptor remoto com propriedades que o SDK lê para cada dispositivo. Esta API gerencia as flags de um aplicativo: as mesmas operações de Audience → Feature Flags no Painel de Controle. Para ler flags em um site ou em um aplicativo móvel, use o Web SDK, o Android SDK ou o iOS SDK.

URL Base

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

Todos os endpoints são servidos via HTTPS. As solicitações e respostas usam application/json.

Autenticação

Toda solicitação deve incluir um cabeçalho Authorization com o seu Token de API do Servidor:

Authorization: Api YOUR_API_TOKEN

Ler flags exige acesso ao aplicativo. Criá-las e alterá-las exige o direito de gerenciá-lo.

Convenções

Nomenclatura de campos: os corpos das solicitações aceitam lowerCamelCase ou snake_case. As respostas usam snake_case, como no Objeto feature flag.
As porcentagens são expressas em pontos-base: percent_bp de 0 a 10000, em que 2000 equivale a 20%.
Versões: toda flag tem uma version. Update, SetRulePercent e Reshuffle recebem a versão que você leu por último e falham com VERSION_CONFLICT quando a flag mudou desde então, para que edições simultâneas nunca sobrescrevam umas às outras. Leia a flag novamente e tente outra vez.
Status: active, killed ou archived. Kill, Unkill, Archive e Restore alteram apenas o status e não recebem versão.

Endpoints

Cada endpoint REST tem uma ferramenta MCP com os mesmos parâmetros:

Método	Caminho	Descrição	Ferramenta MCP
`GET`	`/api/applications/{application_code}/feature_flags`	Listar as flags do aplicativo	`list_feature_flags`
`GET`	`/api/applications/{application_code}/feature_flags/{key}`	Obter uma flag	`get_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags`	Criar uma flag	`create_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}`	Substituir nome, descrição, propriedades e regras	`update_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/rules/{rule_id}/percent`	Alterar o rollout de uma regra	`set_feature_flag_rule_percent`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/kill`	Desativar a flag para todos	`kill_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/unkill`	Reativar uma flag desativada	`unkill_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/archive`	Arquivar uma flag	`archive_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/restore`	Restaurar uma flag arquivada	`restore_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/reshuffle`	Escolher uma nova amostra de usuários	`reshuffle_feature_flag`
`GET`	`/api/applications/{application_code}/feature_flags/{key}/history`	Listar as alterações de uma flag	`list_feature_flag_history`

Todos os endpoints, exceto List e History, retornam { "flag": { ... } }, o Objeto feature flag após a operação.

Listar

GET /api/applications/{application_code}/feature_flags

A solicitação recebe estes parâmetros:

Parâmetro	Local	Tipo	Descrição
`application_code`	path	string	O código do aplicativo.
`status`	query	string	Opcional. `active`, `killed` ou `archived`. Omita para listar todas as flags.

Retorna { "flags": [ ... ] }, um array de Objetos feature flag.

Obter

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

Retorna uma flag com suas propriedades, regras e version atual.

Criar

Cria uma flag ativa. O servidor gera o rule_id de cada regra.

POST /api/applications/{application_code}/feature_flags

O corpo da solicitação tem estes campos:

Parâmetro	Tipo	Obrigatório	Descrição
`key`	string	Sim	Corresponde a `^[A-Za-z0-9_.-]{1,58}$`. Única no aplicativo, incluindo flags arquivadas, comparada sem diferenciar maiúsculas de minúsculas. Não pode ser alterada depois.
`name`	string	Não	Nome de exibição, até 255 caracteres.
`description`	string	Não	Descrição.
`properties`	array de Objetos propriedade	Não	Até 50 propriedades.
`defaults`	object	Sim, se houver propriedades	O valor de cada propriedade para os dispositivos em que a flag está desativada, indexado pela chave da propriedade. Cada valor deve corresponder ao tipo da propriedade.
`rules`	array de Objetos regra	Não	Regras ordenadas, até 10. Decide a primeira regra cujo segmento corresponde ao dispositivo.

Exemplo de solicitação

{
  "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" }
    }
  ]
}

Atualizar

Substitui o nome, a descrição, as propriedades, os valores padrão e as regras de uma flag. O status nunca muda aqui. Envie todos os campos, não apenas os alterados.

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

Recebe o mesmo corpo de Criar sem key, mais a version da sua última leitura. Mantenha o rule_id de cada regra existente. Uma regra sem rule_id é criada como nova. O tipo de uma propriedade não pode mudar depois que a propriedade é criada.

SetRulePercent

Altera o rollout de uma regra. Os usuários que já têm a flag a mantêm quando a porcentagem aumenta.

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

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

Kill e Unkill

POST .../feature_flags/{key}/kill desativa a flag para todos os dispositivos, que passam a receber os valores padrão das propriedades. As regras e as propriedades são mantidas.

POST .../feature_flags/{key}/unkill reativa uma flag desativada com as regras como estavam.

Ambos recebem um corpo vazio {}.

Arquivar e restaurar

POST .../feature_flags/{key}/archive deixa de enviar a flag aos dispositivos. Uma flag arquivada não conta para o limite de flags por aplicativo do plano, e sua chave continua reservada.

POST .../feature_flags/{key}/restore traz de volta uma flag arquivada como killed, para que ela nunca seja ativada sozinha. Chame unkill para fazer o rollout dela novamente.

Ambos recebem um corpo vazio {}.

Redistribuir

Coloca cada usuário em um novo bucket, de modo que as mesmas porcentagens selecionem uma amostra diferente de usuários. Alguns usuários com a flag ativada a perdem, e outros a recebem.

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

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

confirm deve ser true. Caso contrário, a solicitação falha com CONFIRM_REQUIRED.

Histórico

Retorna as alterações de uma flag, da mais recente para a mais antiga: quem fez cada alteração, quando e quais campos mudaram. Assim como Get, exige acesso ao aplicativo e retorna 404 quando o aplicativo ou a flag não existe.

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

A solicitação recebe estes parâmetros:

Parâmetro	Local	Tipo	Descrição
`application_code`	path	string	O código do aplicativo.
`key`	path	string	A chave da flag.
`page`	query	integer	Opcional. Número da página, começando em `0`.
`per_page`	query	integer	Opcional. Entradas por página, `20` por padrão, até `100`.

Retorna { "entries": [ ... ], "total": N }, em que total é o número de entradas em todas as páginas. Cada entrada tem estes campos:

Campo	Tipo	Descrição
`version`	integer	A versão da flag gerada por esta alteração.
`action`	string	`create`, `update`, `set_percent`, `kill`, `unkill`, `archive`, `restore` ou `reshuffle`.
`user_id`	string	O ID do usuário do Painel de Controle que fez a alteração. `0` para uma alteração feita com um token de API ou por um serviço do Pushwoosh.
`user_email`	string	O e-mail desse usuário. Vazio quando o usuário foi excluído ou `user_id` é `0`.
`by_api_token`	boolean	`true` quando a alteração foi feita com um token de API. `false` para uma alteração feita por um usuário ou por um serviço do Pushwoosh.
`api_token_name`	string	O nome que o token de API tinha no momento da alteração. Ele permanece depois que o token é excluído. Vazio quando o token não tem nome ou `by_api_token` é `false`.
`created`	string	Hora da alteração, RFC 3339.
`flag`	Objeto feature flag	A flag após a alteração.
`changes`	array	Os campos que diferem da versão anterior. Vazio para `create` e `reshuffle`, e para a entrada mais antiga de uma flag criada antes de o histórico ser registrado, porque não há versão anterior para comparar.

Cada item de changes tem field, before e after. before e after contêm os valores codificados como strings JSON, portanto um valor do tipo string vem entre aspas. field assume estes valores:

`field`	O que mudou
`name`, `description`, `status`	O campo da flag com este nome.
`properties`	As propriedades e seus valores padrão.
`rules[<rule_id>]`	Uma regra. Para uma regra adicionada, `before` fica vazio. Para uma regra removida, `after` fica vazio.
`rules.order`	A ordem das regras.

Exemplo de resposta

{
  "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
}

O objeto flag no exemplo está abreviado. O histórico é registrado para alterações a partir de 13 de outubro de 2026. Uma flag sem alterações registradas não retorna entradas.

Ler flags para um dispositivo

Os SDKs leem as flags de um endpoint separado. Você não precisa chamá-lo quando usa o Web SDK, o Android SDK ou o iOS SDK, porque eles escolhem o host e armazenam a resposta em cache por conta própria.

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

O corpo da solicitação tem estes campos:

Campo	Tipo	Descrição
`application`	string	O código do aplicativo.
`hwid`	string	O HWID do dispositivo.
`etag`	string	Opcional. O `etag` da última resposta que o dispositivo tem.

A resposta tem estes campos:

Campo	Tipo	Descrição
`flags`	object	Flags indexadas pela chave da flag. Cada uma tem `enabled`, `rule_id` e `properties`. `rule_id` é `default` quando nenhuma regra correspondeu e fica vazio para uma flag desativada. Flags arquivadas não são incluídas.
`etag`	string	Envie-o na próxima solicitação.
`not_modified`	boolean	`true` quando o `etag` enviado está atualizado. Nesse caso, `flags` é omitido e o dispositivo mantém sua cópia.
`partial`	boolean	`true` quando os segmentos do dispositivo não foram avaliados a tempo. Não armazene esta resposta em cache.

Em um plano sem feature flags, a resposta é vazia.

Objetos

Objeto feature flag

Todos os endpoints retornam a flag neste formato:

Campo	Tipo	Descrição
`application_code`	string	O aplicativo ao qual a flag pertence.
`key`	string	A chave da flag.
`name`	string	Nome de exibição.
`description`	string	Descrição.
`status`	string	`active`, `killed` ou `archived`.
`properties`	array de Objetos propriedade	As propriedades da flag.
`defaults`	object	O valor de cada propriedade para os dispositivos em que a flag está desativada.
`rules`	array de Objetos regra	Regras ordenadas.
`version`	integer	Envie-a de volta com `Update`, `SetRulePercent` e `Reshuffle`.
`created`	string	Hora de criação, RFC 3339.
`updated`	string	Hora da última alteração, RFC 3339.
`last_modified_by_user_id`	string	O usuário do Painel de Controle que alterou a flag por último. `0` quando a última alteração foi feita com um token de API ou por um serviço do Pushwoosh.

Objeto propriedade

Uma propriedade descreve um valor que o SDK lê da flag:

Campo	Tipo	Descrição
`key`	string	Corresponde a `^[A-Za-z0-9_]{1,64}$`, única dentro da flag.
`type`	string	`string`, `number`, `boolean` ou `json`. Não pode mudar depois que a propriedade existe.

Objeto regra

Uma regra decide quem recebe a flag ativada e com quais valores:

Campo	Tipo	Descrição
`rule_id`	string	Gerado pelo servidor, `r_` seguido de 8 dígitos hexadecimais, e estável entre atualizações. Deixe vazio para uma nova regra.
`name`	string	Nome da regra.
`filter_code`	string	O segmento ao qual o dispositivo deve corresponder. Vazio corresponde a todos os dispositivos. O segmento só pode conter condições de tag, localização, aplicativo e lista.
`percent_bp`	integer	Parcela dos usuários correspondentes para os quais a flag está ativada, `0`–`10000`. Um dispositivo que corresponde ao segmento para nesta regra mesmo quando fica fora da porcentagem.
`overrides`	object	Valores de propriedades que substituem os padrões para os dispositivos em que esta regra ativa a flag, indexados pela chave da propriedade.

Erros

Uma solicitação rejeitada retorna um destes códigos de status HTTP:

Status HTTP	Significado
`400 Bad Request`	A solicitação é inválida (`field_violations`) ou o estado da flag ou o plano não a permite (`Type`). Veja os formatos do corpo e os motivos abaixo.
`401 Unauthorized`	O cabeçalho `Authorization` está ausente ou o token é inválido.
`403 Forbidden`	O token não pode gerenciar o aplicativo, ou o aplicativo é do sistema.
`404 Not Found`	O aplicativo ou a flag não existe.
`409 Conflict`	Outra solicitação está alterando a mesma flag neste momento. Tente a solicitação novamente.
`500 Internal Server Error`	Falha inesperada do servidor. O corpo é `{"message": "Sorry, an unexpected error occurred"}`.

Uma solicitação inválida retorna 400 com uma lista de violações de campo. Cada violação indica o campo, o motivo e os argumentos do motivo:

{
  "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" }
        }
      ]
    }
  ]
}

Uma solicitação que o estado da flag ou o plano não permite retorna 400 com uma pré-condição com falha. Seus campos Type e Description começam com letra maiúscula:

{
  "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"
    }
  ]
}

O reason de uma violação de campo e o Type de uma pré-condição com falha assumem estes valores:

Motivo	Causa
`KEY_INVALID`	A chave não corresponde a `^[A-Za-z0-9_.-]{1,58}$`.
`KEY_TAKEN`	Outra flag do aplicativo, incluindo as arquivadas, tem esta chave.
`TEXT_INVALID`	O nome ou a descrição é longo demais ou contém caracteres proibidos.
`PROPERTIES_LIMIT`	Mais de 50 propriedades.
`PROPERTY_KEY_INVALID`	Uma chave de propriedade é inválida ou repetida.
`PROPERTY_TYPE_INVALID`	Um tipo de propriedade não é `string`, `number`, `boolean` nem `json`.
`PROPERTY_TYPE_IMMUTABLE`	A solicitação altera o tipo de uma propriedade existente.
`VALUE_INVALID`	Um valor padrão ou de substituição está ausente, não corresponde ao tipo da propriedade ou está aninhado em mais de 5 níveis.
`PROPERTIES_TOO_LARGE`	Os valores das propriedades da flag excedem 10.000 bytes.
`RULES_LIMIT`	Mais de 10 regras.
`RULE_NOT_FOUND`	O `rule_id` não é uma das regras da flag.
`PERCENT_INVALID`	`percent_bp` está fora de `0`–`10000`.
`OVERRIDE_UNKNOWN_PROPERTY`	Uma substituição cita uma propriedade que a flag não tem.
`SEGMENT_NOT_FOUND`	O segmento da regra não existe ou pertence a outro aplicativo.
`INVALID_SEGMENT_TYPE`	O segmento da regra tem uma condição que as flags não conseguem avaliar: evento, estático, externo, última atualização ou melhor horário de envio.
`FLAG_DEPENDENCY`	O segmento da regra tem uma condição de feature flag, e uma flag não pode depender de outra flag. Retornado por `Create`, `Update` e `Restore`, com o código do segmento em `filter_code`.
`CONFIRM_REQUIRED`	`Reshuffle` foi enviado sem `confirm: true`.
`TAG_CONFLICT`	A conta tem uma tag personalizada chamada `PW_FF_` seguida da chave da flag.
`FEATURE_FLAGS_NOT_ALLOWED`	O plano da conta não inclui feature flags.
`FLAGS_LIMIT`	O aplicativo tem tantas flags não arquivadas quanto o plano permite.
`VERSION_CONFLICT`	A flag mudou desde a `version` que você enviou.
`PAYLOAD_TOO_LARGE`	As flags do aplicativo ocupariam mais de 64 KB na resposta a um dispositivo.
`STATUS_CONFLICT`	O status não permite a operação, por exemplo, desativar uma flag arquivada.