Feature-Flags-API

Ein Feature-Flag ist ein Fernschalter mit Eigenschaften, die das SDK für jedes Gerät ausliest. Diese API verwaltet die Flags einer Anwendung: dieselben Vorgänge wie unter Audience → Feature Flags im Control Panel. Um Flags auf einer Website oder in einer mobilen App auszulesen, verwenden Sie das Web SDK, das Android SDK oder das iOS SDK.

Basis-URL

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

Alle Endpunkte werden über HTTPS bereitgestellt. Anfragen und Antworten verwenden application/json.

Authentifizierung

Jede Anfrage muss einen Authorization-Header mit Ihrem Server-API-Token enthalten:

Authorization: Api YOUR_API_TOKEN

Zum Lesen von Flags ist Zugriff auf die Anwendung erforderlich. Zum Erstellen und Ändern ist das Recht erforderlich, die Anwendung zu verwalten.

Konventionen

Feldbenennung: Anfragekörper akzeptieren lowerCamelCase oder snake_case. Antworten verwenden snake_case, wie im Feature-Flag-Objekt.
Prozentwerte werden in Basispunkten angegeben: percent_bp von 0 bis 10000, wobei 2000 20 % entspricht.
Versionen: Jedes Flag trägt eine version. Update, SetRulePercent und Reshuffle erwarten die zuletzt gelesene Version und schlagen mit VERSION_CONFLICT fehl, wenn sich das Flag seitdem geändert hat, sodass gleichzeitige Änderungen einander nie überschreiben. Lesen Sie das Flag erneut und wiederholen Sie den Vorgang.
Status: active, killed oder archived. Kill, Unkill, Archive und Restore ändern nur den Status und erwarten keine Version.

Endpunkte

Zu jedem REST-Endpunkt gibt es ein MCP-Tool mit denselben Parametern:

Methode	Pfad	Beschreibung	MCP-Tool
`GET`	`/api/applications/{application_code}/feature_flags`	Flags der Anwendung auflisten	`list_feature_flags`
`GET`	`/api/applications/{application_code}/feature_flags/{key}`	Ein Flag abrufen	`get_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags`	Ein Flag erstellen	`create_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}`	Name, Beschreibung, Eigenschaften und Regeln ersetzen	`update_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/rules/{rule_id}/percent`	Den Rollout einer Regel ändern	`set_feature_flag_rule_percent`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/kill`	Das Flag für alle deaktivieren	`kill_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/unkill`	Ein deaktiviertes Flag wieder aktivieren	`unkill_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/archive`	Ein Flag archivieren	`archive_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/restore`	Ein archiviertes Flag wiederherstellen	`restore_feature_flag`
`POST`	`/api/applications/{application_code}/feature_flags/{key}/reshuffle`	Eine neue Stichprobe von Nutzern auswählen	`reshuffle_feature_flag`
`GET`	`/api/applications/{application_code}/feature_flags/{key}/history`	Die Änderungen eines Flags auflisten	`list_feature_flag_history`

Alle Endpunkte außer List und History geben { "flag": { ... } } zurück, das Feature-Flag-Objekt nach dem Vorgang.

List

GET /api/applications/{application_code}/feature_flags

Die Anfrage akzeptiert diese Parameter:

Parameter	Ort	Typ	Beschreibung
`application_code`	path	string	Der Application code.
`status`	query	string	Optional. `active`, `killed` oder `archived`. Weglassen, um alle Flags aufzulisten.

Gibt { "flags": [ ... ] } zurück, ein Array von Feature-Flag-Objekten.

Get

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

Gibt ein Flag mit seinen Eigenschaften, Regeln und der aktuellen version zurück.

Create

Erstellt ein aktives Flag. Der Server generiert die rule_id jeder Regel.

POST /api/applications/{application_code}/feature_flags

Der Anfragekörper enthält diese Felder:

Parameter	Typ	Erforderlich	Beschreibung
`key`	string	Ja	Entspricht `^[A-Za-z0-9_.-]{1,58}$`. Eindeutig in der Anwendung, archivierte Flags eingeschlossen, ohne Beachtung der Groß-/Kleinschreibung verglichen. Kann später nicht geändert werden.
`name`	string	Nein	Anzeigename, bis zu 255 Zeichen.
`description`	string	Nein	Beschreibung.
`properties`	Array von Property-Objekten	Nein	Bis zu 50 Eigenschaften.
`defaults`	object	Ja, wenn Eigenschaften vorhanden sind	Der Wert jeder Eigenschaft für Geräte, für die das Flag deaktiviert ist, nach Eigenschaftsschlüssel. Jeder Wert muss dem Eigenschaftstyp entsprechen.
`rules`	Array von Rule-Objekten	Nein	Geordnete Regeln, bis zu 10. Es entscheidet die erste Regel, deren Segment auf das Gerät zutrifft.

Anfragebeispiel

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

Update

Ersetzt Name, Beschreibung, Eigenschaften, Standardwerte und Regeln eines Flags. Der Status ändert sich hier nie. Senden Sie alle Felder, nicht nur die geänderten.

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

Erwartet denselben Körper wie Create ohne key, zuzüglich der version aus Ihrem letzten Lesevorgang. Behalten Sie die rule_id jeder bestehenden Regel bei. Eine Regel ohne rule_id wird neu erstellt. Der Typ einer Eigenschaft kann nach ihrer Erstellung nicht mehr geändert werden.

SetRulePercent

Ändert den Rollout einer Regel. Nutzer, die das Flag bereits haben, behalten es, wenn der Prozentsatz steigt.

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

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

Kill und Unkill

POST .../feature_flags/{key}/kill deaktiviert das Flag für jedes Gerät, das dann die Standardwerte der Eigenschaften erhält. Regeln und Eigenschaften bleiben erhalten.

POST .../feature_flags/{key}/unkill aktiviert ein deaktiviertes Flag wieder, mit seinen Regeln im vorherigen Zustand.

Beide erwarten einen leeren Körper {}.

Archive und Restore

POST .../feature_flags/{key}/archive beendet das Senden des Flags an Geräte. Ein archiviertes Flag zählt nicht zum Tariflimit für Flags pro Anwendung, und sein Schlüssel bleibt reserviert.

POST .../feature_flags/{key}/restore stellt ein archiviertes Flag als killed wieder her, sodass es sich nie von selbst aktiviert. Rufen Sie unkill auf, um es erneut auszurollen.

Beide erwarten einen leeren Körper {}.

Reshuffle

Ordnet jeden Nutzer einem neuen Bucket zu, sodass dieselben Prozentsätze eine andere Stichprobe von Nutzern auswählen. Einige Nutzer, bei denen das Flag aktiv ist, verlieren es, und andere erhalten es.

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

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

confirm muss true sein. Andernfalls schlägt die Anfrage mit CONFIRM_REQUIRED fehl.

History

Gibt die Änderungen eines Flags zurück, die neueste zuerst: wer jede Änderung vorgenommen hat, wann und welche Felder sich geändert haben. Wie Get erfordert der Aufruf Zugriff auf die Anwendung und gibt 404 zurück, wenn die Anwendung oder das Flag nicht existiert.

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

Die Anfrage akzeptiert diese Parameter:

Parameter	Ort	Typ	Beschreibung
`application_code`	path	string	Der Application code.
`key`	path	string	Der Schlüssel des Flags.
`page`	query	integer	Optional. Seitennummer, beginnend bei `0`.
`per_page`	query	integer	Optional. Einträge pro Seite, standardmäßig `20`, höchstens `100`.

Gibt { "entries": [ ... ], "total": N } zurück, wobei total die Anzahl der Einträge über alle Seiten ist. Jeder Eintrag hat diese Felder:

Feld	Typ	Beschreibung
`version`	integer	Die Version des Flags, die durch diese Änderung entstanden ist.
`action`	string	`create`, `update`, `set_percent`, `kill`, `unkill`, `archive`, `restore` oder `reshuffle`.
`user_id`	string	Die ID des Control-Panel-Nutzers, der die Änderung vorgenommen hat. `0` für eine Änderung mit einem API-Token oder durch einen Pushwoosh-Dienst.
`user_email`	string	Die E-Mail-Adresse dieses Nutzers. Leer, wenn der Nutzer gelöscht wurde oder `user_id` `0` ist.
`by_api_token`	boolean	`true`, wenn die Änderung mit einem API-Token vorgenommen wurde. `false` für eine Änderung durch einen Nutzer oder einen Pushwoosh-Dienst.
`api_token_name`	string	Der Name, den das API-Token zum Zeitpunkt der Änderung hatte. Er bleibt erhalten, nachdem das Token gelöscht wurde. Leer, wenn das Token keinen Namen hat oder `by_api_token` `false` ist.
`created`	string	Zeitpunkt der Änderung, RFC 3339.
`flag`	Feature-Flag-Objekt	Das Flag nach der Änderung.
`changes`	array	Die Felder, die sich von der vorherigen Version unterscheiden. Leer für `create` und `reshuffle` sowie für den ältesten Eintrag eines Flags, das vor Beginn der Verlaufsaufzeichnung erstellt wurde, weil es keine frühere Version zum Vergleich gibt.

Jedes Element von changes hat field, before und after. before und after enthalten die Werte als JSON-kodierte Strings, ein String-Wert steht also in Anführungszeichen. field nimmt diese Werte an:

`field`	Was sich geändert hat
`name`, `description`, `status`	Das Feld des Flags mit diesem Namen.
`properties`	Die Eigenschaften und ihre Standardwerte.
`rules[<rule_id>]`	Eine Regel. Bei einer hinzugefügten Regel ist `before` leer. Bei einer entfernten Regel ist `after` leer.
`rules.order`	Die Reihenfolge der Regeln.

Antwortbeispiel

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

Das flag-Objekt im Beispiel ist gekürzt. Der Verlauf wird für Änderungen ab dem 13. Oktober 2026 aufgezeichnet. Ein Flag ohne aufgezeichnete Änderungen gibt keine Einträge zurück.

Flags für ein Gerät auslesen

Die SDKs lesen Flags über einen separaten Endpunkt aus. Sie rufen ihn nicht auf, wenn Sie das Web SDK, das Android SDK oder das iOS SDK verwenden, da diese den Host selbst wählen und die Antwort selbst zwischenspeichern.

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

Der Anfragekörper hat diese Felder:

Feld	Typ	Beschreibung
`application`	string	Der Application code.
`hwid`	string	Die HWID des Geräts.
`etag`	string	Optional. Das `etag` der letzten Antwort, die das Gerät vorhält.

Die Antwort hat diese Felder:

Feld	Typ	Beschreibung
`flags`	object	Flags nach Flag-Schlüssel. Jedes hat `enabled`, `rule_id` und `properties`. `rule_id` ist `default`, wenn keine Regel zutraf, und leer für ein deaktiviertes Flag. Archivierte Flags sind nicht enthalten.
`etag`	string	Senden Sie es mit der nächsten Anfrage.
`not_modified`	boolean	`true`, wenn das gesendete `etag` aktuell ist. `flags` entfällt dann, und das Gerät behält seine Kopie.
`partial`	boolean	`true`, wenn die Segmente des Geräts nicht rechtzeitig abgeglichen wurden. Speichern Sie diese Antwort nicht zwischen.

In einem Tarif ohne Feature-Flags ist die Antwort leer.

Objekte

Feature-Flag-Objekt

Jeder Endpunkt gibt das Flag in dieser Form zurück:

Feld	Typ	Beschreibung
`application_code`	string	Die Anwendung, zu der das Flag gehört.
`key`	string	Der Schlüssel des Flags.
`name`	string	Anzeigename.
`description`	string	Beschreibung.
`status`	string	`active`, `killed` oder `archived`.
`properties`	Array von Property-Objekten	Die Eigenschaften des Flags.
`defaults`	object	Der Wert jeder Eigenschaft für Geräte, für die das Flag deaktiviert ist.
`rules`	Array von Rule-Objekten	Geordnete Regeln.
`version`	integer	Senden Sie sie mit `Update`, `SetRulePercent` und `Reshuffle` zurück.
`created`	string	Erstellungszeitpunkt, RFC 3339.
`updated`	string	Zeitpunkt der letzten Änderung, RFC 3339.
`last_modified_by_user_id`	string	Der Control-Panel-Nutzer, der das Flag zuletzt geändert hat. `0`, wenn die letzte Änderung mit einem API-Token oder von einem Pushwoosh-Dienst vorgenommen wurde.

Property-Objekt

Eine Eigenschaft beschreibt einen Wert, den das SDK aus dem Flag ausliest:

Feld	Typ	Beschreibung
`key`	string	Entspricht `^[A-Za-z0-9_]{1,64}$`, eindeutig innerhalb des Flags.
`type`	string	`string`, `number`, `boolean` oder `json`. Kann nicht mehr geändert werden, sobald die Eigenschaft existiert.

Rule-Objekt

Eine Regel entscheidet, bei wem das Flag aktiv ist und mit welchen Werten:

Feld	Typ	Beschreibung
`rule_id`	string	Vom Server generiert, `r_` gefolgt von 8 Hexadezimalziffern, und über Aktualisierungen hinweg stabil. Lassen Sie das Feld für eine neue Regel leer.
`name`	string	Name der Regel.
`filter_code`	string	Das Segment, auf das das Gerät zutreffen muss. Leer trifft auf jedes Gerät zu. Das Segment darf nur Tag-, Standort-, Anwendungs- und Listenbedingungen enthalten.
`percent_bp`	integer	Anteil der zutreffenden Nutzer, für die das Flag aktiv ist, `0`–`10000`. Ein Gerät, das auf das Segment zutrifft, bleibt bei dieser Regel stehen, auch wenn es außerhalb des Prozentsatzes liegt.
`overrides`	object	Eigenschaftswerte, die die Standardwerte für Geräte ersetzen, die diese Regel aktiviert, nach Eigenschaftsschlüssel.

Fehler

Eine abgelehnte Anfrage gibt einen dieser HTTP-Statuscodes zurück:

HTTP-Status	Bedeutung
`400 Bad Request`	Die Anfrage ist ungültig (`field_violations`), oder der Zustand des Flags bzw. der Tarif lässt sie nicht zu (`Type`). Die Körperformate und Gründe finden Sie unten.
`401 Unauthorized`	Der `Authorization`-Header fehlt oder das Token ist ungültig.
`403 Forbidden`	Das Token kann die Anwendung nicht verwalten, oder es handelt sich um eine Systemanwendung.
`404 Not Found`	Die Anwendung oder das Flag existiert nicht.
`409 Conflict`	Eine andere Anfrage ändert gerade dasselbe Flag. Wiederholen Sie die Anfrage.
`500 Internal Server Error`	Unerwarteter Serverfehler. Der Körper lautet `{"message": "Sorry, an unexpected error occurred"}`.

Eine ungültige Anfrage gibt 400 mit einer Liste von Feldverletzungen zurück. Jede Verletzung nennt das Feld, den Grund und die Argumente des Grundes:

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

Eine Anfrage, die der Zustand des Flags oder der Tarif nicht zulässt, gibt 400 mit einer fehlgeschlagenen Vorbedingung zurück. Ihre Felder Type und Description werden großgeschrieben:

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

Der reason einer Feldverletzung und der Type einer fehlgeschlagenen Vorbedingung nehmen diese Werte an:

Grund	Ursache
`KEY_INVALID`	Der Schlüssel entspricht nicht `^[A-Za-z0-9_.-]{1,58}$`.
`KEY_TAKEN`	Ein anderes Flag der Anwendung, archivierte eingeschlossen, hat diesen Schlüssel.
`TEXT_INVALID`	Name oder Beschreibung ist zu lang oder enthält unzulässige Zeichen.
`PROPERTIES_LIMIT`	Mehr als 50 Eigenschaften.
`PROPERTY_KEY_INVALID`	Ein Eigenschaftsschlüssel ist ungültig oder doppelt vorhanden.
`PROPERTY_TYPE_INVALID`	Ein Eigenschaftstyp ist nicht `string`, `number`, `boolean` oder `json`.
`PROPERTY_TYPE_IMMUTABLE`	Die Anfrage ändert den Typ einer bestehenden Eigenschaft.
`VALUE_INVALID`	Ein Standard- oder Override-Wert fehlt, entspricht nicht dem Eigenschaftstyp oder ist tiefer als 5 Ebenen verschachtelt.
`PROPERTIES_TOO_LARGE`	Die Eigenschaftswerte des Flags überschreiten 10.000 Byte.
`RULES_LIMIT`	Mehr als 10 Regeln.
`RULE_NOT_FOUND`	Die `rule_id` gehört zu keiner Regel des Flags.
`PERCENT_INVALID`	`percent_bp` liegt außerhalb von `0`–`10000`.
`OVERRIDE_UNKNOWN_PROPERTY`	Ein Override nennt eine Eigenschaft, die das Flag nicht hat.
`SEGMENT_NOT_FOUND`	Das Segment der Regel existiert nicht oder gehört zu einer anderen Anwendung.
`INVALID_SEGMENT_TYPE`	Das Segment der Regel enthält eine Bedingung, die Flags nicht auswerten können: Event, statisch, extern, letzte Aktualisierung oder beste Sendezeit.
`FLAG_DEPENDENCY`	Das Segment der Regel enthält eine Feature-Flag-Bedingung, und ein Flag kann nicht von einem anderen Flag abhängen. Wird von `Create`, `Update` und `Restore` zurückgegeben, mit dem Segmentcode in `filter_code`.
`CONFIRM_REQUIRED`	`Reshuffle` wurde ohne `confirm: true` gesendet.
`TAG_CONFLICT`	Das Konto hat einen benutzerdefinierten Tag mit dem Namen `PW_FF_` gefolgt vom Schlüssel des Flags.
`FEATURE_FLAGS_NOT_ALLOWED`	Der Tarif des Kontos enthält keine Feature-Flags.
`FLAGS_LIMIT`	Die Anwendung hat so viele nicht archivierte Flags, wie der Tarif erlaubt.
`VERSION_CONFLICT`	Das Flag hat sich seit der gesendeten `version` geändert.
`PAYLOAD_TOO_LARGE`	Die Flags der Anwendung würden in der Antwort an ein Gerät mehr als 64 KB belegen.
`STATUS_CONFLICT`	Der Status lässt den Vorgang nicht zu, zum Beispiel das Deaktivieren eines archivierten Flags.