सामग्री पर जाएं

फ़ीचर फ़्लैग API

फ़ीचर फ़्लैग प्रॉपर्टीज़ वाला एक रिमोट स्विच है, जिसे SDK हर डिवाइस के लिए पढ़ता है। यह API किसी एप्लिकेशन के फ़्लैग का प्रबंधन करता है: कंट्रोल पैनल में Audience → Feature Flags वाले ही ऑपरेशन। किसी वेबसाइट या मोबाइल ऐप में फ़्लैग पढ़ने के लिए Web SDK, Android SDK या iOS SDK का उपयोग करें।

बेस यूआरएल

Anchor link to
https://rpc-api.svc-nue.pushwoosh.com

सभी एंडपॉइंट्स HTTPS पर सर्व किए जाते हैं। अनुरोध और प्रतिक्रियाएं application/json का उपयोग करती हैं।

प्रमाणीकरण

Anchor link to

प्रत्येक अनुरोध में आपके सर्वर API टोकन के साथ एक Authorization हेडर शामिल होना चाहिए:

Authorization: Api YOUR_API_TOKEN

फ़्लैग पढ़ने के लिए एप्लिकेशन तक एक्सेस आवश्यक है। उन्हें बनाने और बदलने के लिए एप्लिकेशन को प्रबंधित करने का अधिकार आवश्यक है।

परंपराएं

Anchor link to
  • फ़ील्ड नेमिंग: रिक्वेस्ट बॉडी lowerCamelCase या snake_case स्वीकार करती है। प्रतिक्रियाएं snake_case का उपयोग करती हैं, जैसा कि फ़ीचर फ़्लैग ऑब्जेक्ट में है।
  • प्रतिशत बेसिस पॉइंट्स में होते हैं: percent_bp 0 से 10000 तक, जहां 2000 का अर्थ 20% है।
  • वर्ज़न: हर फ़्लैग में एक version होता है। Update, SetRulePercent और Reshuffle वह वर्ज़न लेते हैं जो आपने आखिरी बार पढ़ा था, और यदि उसके बाद फ़्लैग बदल गया है तो VERSION_CONFLICT के साथ विफल हो जाते हैं, ताकि एक साथ किए गए संपादन कभी एक-दूसरे को ओवरराइट न करें। फ़्लैग को फिर से पढ़ें और दोबारा प्रयास करें।
  • स्टेटस: active, killed या archived। Kill, Unkill, Archive और Restore केवल स्टेटस बदलते हैं और कोई वर्ज़न नहीं लेते।

एंडपॉइंट्स

Anchor link to

हर 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": { ... } } लौटाता है, यानी ऑपरेशन के बाद का फ़ीचर फ़्लैग ऑब्जेक्ट।

सूची

Anchor link to

GET /api/applications/{application_code}/feature_flags

अनुरोध ये पैरामीटर लेता है:

पैरामीटरस्थानप्रकारविवरण
application_codepathstringएप्लिकेशन कोड।
statusquerystringवैकल्पिक। active, killed या archived। सभी फ़्लैग की सूची पाने के लिए इसे छोड़ दें।

{ "flags": [ ... ] } लौटाता है, यानी फ़ीचर फ़्लैग ऑब्जेक्ट्स का एक ऐरे।

प्राप्त करें

Anchor link to

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

एक फ़्लैग को उसकी प्रॉपर्टीज़, नियमों और वर्तमान version के साथ लौटाता है।

बनाएं

Anchor link to

एक active फ़्लैग बनाता है। सर्वर हर नियम का rule_id जनरेट करता है।

POST /api/applications/{application_code}/feature_flags

रिक्वेस्ट बॉडी में ये फ़ील्ड होते हैं:

पैरामीटरप्रकारआवश्यकविवरण
keystringहाँ^[A-Za-z0-9_.-]{1,58}$ से मेल खाता है। एप्लिकेशन में अद्वितीय, आर्काइव किए गए फ़्लैग सहित, और केस-इनसेंसिटिव तरीके से तुलना की जाती है। बाद में बदला नहीं जा सकता।
namestringनहींडिस्प्ले नाम, अधिकतम 255 वर्ण।
descriptionstringनहींविवरण।
propertiesप्रॉपर्टी ऑब्जेक्ट्स का ऐरेनहींअधिकतम 50 प्रॉपर्टीज़।
defaultsobjectहाँ, यदि प्रॉपर्टीज़ हैंउन डिवाइसों के लिए हर प्रॉपर्टी का मान जिनके लिए फ़्लैग बंद है, प्रॉपर्टी की के अनुसार। हर मान प्रॉपर्टी के प्रकार से मेल खाना चाहिए।
rulesनियम ऑब्जेक्ट्स का ऐरेनहींक्रमबद्ध नियम, अधिकतम 10। जिस पहले नियम का सेगमेंट डिवाइस से मेल खाता है, वही निर्णय लेता है।
अनुरोध उदाहरण
Anchor link to
{
"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" }
}
]
}

अपडेट करें

Anchor link to

किसी फ़्लैग का नाम, विवरण, प्रॉपर्टीज़, डिफ़ॉल्ट और नियम बदल देता है। यहां स्टेटस कभी नहीं बदलता। सभी फ़ील्ड भेजें, केवल बदले हुए नहीं।

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

बनाएं जैसी ही बॉडी लेता है, key के बिना, साथ में आपके आखिरी बार पढ़े गए version के साथ। हर मौजूदा नियम का rule_id बनाए रखें। rule_id के बिना नियम नए नियम के रूप में बनाया जाता है। प्रॉपर्टी बनाए जाने के बाद उसका प्रकार नहीं बदला जा सकता।

SetRulePercent

Anchor link to

एक नियम का रोलआउट बदलता है। प्रतिशत बढ़ने पर जिन उपयोगकर्ताओं के पास पहले से फ़्लैग है, वे उसे बनाए रखते हैं।

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

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

Kill और Unkill

Anchor link to

POST .../feature_flags/{key}/kill हर डिवाइस के लिए फ़्लैग बंद कर देता है, जिसके बाद डिवाइस को डिफ़ॉल्ट प्रॉपर्टी मान मिलते हैं। नियम और प्रॉपर्टीज़ बनी रहती हैं।

POST .../feature_flags/{key}/unkill बंद किए गए फ़्लैग को उसके नियमों के साथ, जैसे वे थे, फिर से चालू करता है।

दोनों एक खाली बॉडी {} लेते हैं।

Archive और Restore

Anchor link to

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 के साथ विफल हो जाता है।

इतिहास

Anchor link to

किसी फ़्लैग के बदलाव लौटाता है, सबसे नए पहले: हर बदलाव किसने किया, कब किया, और कौन-से फ़ील्ड बदले। Get की तरह, इसके लिए एप्लिकेशन तक पहुंच चाहिए, और एप्लिकेशन या फ़्लैग मौजूद न होने पर यह 404 लौटाता है।

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

अनुरोध ये पैरामीटर लेता है:

पैरामीटरस्थानप्रकारविवरण
application_codepathstringएप्लिकेशन कोड।
keypathstringफ़्लैग की कुंजी।
pagequeryintegerवैकल्पिक। पेज नंबर, 0 से शुरू।
per_pagequeryintegerवैकल्पिक। प्रति पेज एंट्री, डिफ़ॉल्ट रूप से 20, अधिकतम 100।

{ "entries": [ ... ], "total": N } लौटाता है, जहां total सभी पेजों की कुल एंट्री की संख्या है। हर एंट्री में ये फ़ील्ड होते हैं:

फ़ील्डप्रकारविवरण
versionintegerइस बदलाव से बना फ़्लैग वर्ज़न।
actionstringcreate, update, set_percent, kill, unkill, archive, restore या reshuffle।
user_idstringबदलाव करने वाले कंट्रोल पैनल उपयोगकर्ता की ID। API टोकन से या किसी Pushwoosh सेवा द्वारा किए गए बदलाव के लिए 0।
user_emailstringउस उपयोगकर्ता का ईमेल। उपयोगकर्ता हटा दिए जाने पर या user_id के 0 होने पर खाली।
by_api_tokenbooleanबदलाव API टोकन से किया गया हो, तो true। किसी उपयोगकर्ता या Pushwoosh सेवा द्वारा किए गए बदलाव के लिए false।
api_token_namestringबदलाव के समय API टोकन का नाम। टोकन हटाए जाने के बाद भी यह बना रहता है। टोकन का कोई नाम न होने पर या by_api_token के false होने पर खाली।
createdstringबदलाव का समय, RFC 3339।
flagफ़ीचर फ़्लैग ऑब्जेक्टबदलाव के बाद का फ़्लैग।
changesarrayवे फ़ील्ड जो पिछले वर्ज़न से अलग हैं। create और reshuffle के लिए खाली, और इतिहास रिकॉर्ड होना शुरू होने से पहले बने फ़्लैग की सबसे पुरानी एंट्री के लिए भी खाली, क्योंकि तुलना के लिए कोई पिछला वर्ज़न नहीं है।

changes के हर आइटम में field, before और after होते हैं। before और after में मान JSON स्ट्रिंग के रूप में एन्कोड होते हैं, इसलिए स्ट्रिंग मान उद्धरण चिह्नों में आता है। field के ये मान हो सकते हैं:

fieldक्या बदला
name, description, statusइस नाम वाला फ़्लैग फ़ील्ड।
propertiesप्रॉपर्टीज़ और उनके डिफ़ॉल्ट मान।
rules[<rule_id>]एक नियम। जोड़े गए नियम के लिए before खाली होता है। हटाए गए नियम के लिए after खाली होता है।
rules.orderनियमों का क्रम।
प्रतिक्रिया उदाहरण
Anchor link to
{
"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 ऑब्जेक्ट छोटा किया गया है। इतिहास 13 अक्टूबर 2026 से हुए बदलावों के लिए रिकॉर्ड होता है। जिस फ़्लैग का कोई बदलाव रिकॉर्ड नहीं है, उसके लिए कोई एंट्री नहीं लौटती।

किसी डिवाइस के लिए फ़्लैग पढ़ें

Anchor link to

SDK फ़्लैग एक अलग एंडपॉइंट से पढ़ते हैं। Web SDK, Android SDK या iOS SDK का उपयोग करते समय आपको इसे कॉल करने की ज़रूरत नहीं है, क्योंकि वे होस्ट खुद चुनते हैं और जवाब खुद कैश करते हैं।

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

अनुरोध बॉडी में ये फ़ील्ड होते हैं:

फ़ील्डप्रकारविवरण
applicationstringएप्लिकेशन कोड।
hwidstringडिवाइस का HWID।
etagstringवैकल्पिक। डिवाइस के पास मौजूद आखिरी जवाब का etag।

प्रतिक्रिया में ये फ़ील्ड होते हैं:

फ़ील्डप्रकारविवरण
flagsobjectफ़्लैग कुंजी के अनुसार फ़्लैग। हर फ़्लैग में enabled, rule_id और properties होते हैं। कोई नियम मेल न खाने पर rule_id का मान default होता है, और बंद किए गए फ़्लैग के लिए यह खाली होता है। आर्काइव किए गए फ़्लैग शामिल नहीं होते।
etagstringइसे अगले अनुरोध के साथ भेजें।
not_modifiedbooleanभेजा गया etag मौजूदा हो, तो true। तब flags नहीं भेजा जाता और डिवाइस अपनी कॉपी रखता है।
partialbooleanडिवाइस के सेगमेंट समय पर मैच न हो पाए हों, तो true। इस जवाब को कैश न करें।

फ़ीचर फ़्लैग के बिना वाले प्लान पर प्रतिक्रिया खाली होती है।

ऑब्जेक्ट्स

Anchor link to

फ़ीचर फ़्लैग ऑब्जेक्ट

Anchor link to

हर एंडपॉइंट फ़्लैग को इस रूप में लौटाता है:

फ़ील्डप्रकारविवरण
application_codestringवह एप्लिकेशन जिससे फ़्लैग संबंधित है।
keystringफ़्लैग की की।
namestringडिस्प्ले नाम।
descriptionstringविवरण।
statusstringactive, killed या archived।
propertiesप्रॉपर्टी ऑब्जेक्ट्स का ऐरेफ़्लैग की प्रॉपर्टीज़।
defaultsobjectउन डिवाइसों के लिए हर प्रॉपर्टी का मान जिनके लिए फ़्लैग बंद है।
rulesनियम ऑब्जेक्ट्स का ऐरेक्रमबद्ध नियम।
versionintegerइसे Update, SetRulePercent और Reshuffle के साथ वापस भेजें।
createdstringबनाए जाने का समय, RFC 3339।
updatedstringआखिरी बदलाव का समय, RFC 3339।
last_modified_by_user_idstringकंट्रोल पैनल का वह उपयोगकर्ता जिसने फ़्लैग को आखिरी बार बदला। जब आखिरी बदलाव API टोकन से या किसी Pushwoosh सेवा द्वारा किया गया हो, तो 0।

प्रॉपर्टी ऑब्जेक्ट

Anchor link to

प्रॉपर्टी एक मान का वर्णन करती है जिसे SDK फ़्लैग से पढ़ता है:

फ़ील्डप्रकारविवरण
keystring^[A-Za-z0-9_]{1,64}$ से मेल खाती है, फ़्लैग के भीतर अद्वितीय।
typestringstring, number, boolean या json। प्रॉपर्टी बन जाने के बाद बदला नहीं जा सकता।

नियम ऑब्जेक्ट

Anchor link to

नियम तय करता है कि किसके लिए फ़्लैग चालू होगा और किन मानों के साथ:

फ़ील्डप्रकारविवरण
rule_idstringसर्वर द्वारा जनरेट किया जाता है, r_ के बाद 8 हेक्स अंक, और अपडेट के दौरान स्थिर रहता है। नए नियम के लिए इसे खाली छोड़ें।
namestringनियम का नाम।
filter_codestringवह सेगमेंट जिससे डिवाइस का मेल खाना आवश्यक है। खाली होने पर हर डिवाइस से मेल खाता है। सेगमेंट में केवल टैग, लोकेशन, एप्लिकेशन और लिस्ट शर्तें हो सकती हैं।
percent_bpintegerमेल खाने वाले उपयोगकर्ताओं का वह हिस्सा जिनके लिए फ़्लैग चालू है, 0–10000। जो डिवाइस सेगमेंट से मेल खाता है, वह इसी नियम पर रुक जाता है, भले ही वह प्रतिशत से बाहर हो।
overridesobjectप्रॉपर्टी मान जो इस नियम द्वारा चालू किए गए डिवाइसों के लिए डिफ़ॉल्ट की जगह लेते हैं, प्रॉपर्टी की के अनुसार।

त्रुटियां

Anchor link to

अस्वीकृत अनुरोध इनमें से कोई एक HTTP स्टेटस कोड लौटाता है:

HTTP स्टेटसअर्थ
400 Bad Requestअनुरोध अमान्य है (field_violations) या फ़्लैग की स्थिति या प्लान इसकी अनुमति नहीं देता (Type)। बॉडी फ़ॉर्मेट और कारण नीचे देखें।
401 UnauthorizedAuthorization हेडर मौजूद नहीं है या टोकन अमान्य है।
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_LIMIT50 से अधिक प्रॉपर्टीज़।
PROPERTY_KEY_INVALIDकोई प्रॉपर्टी की अमान्य है या दोहराई गई है।
PROPERTY_TYPE_INVALIDकोई प्रॉपर्टी प्रकार string, number, boolean या json नहीं है।
PROPERTY_TYPE_IMMUTABLEअनुरोध किसी मौजूदा प्रॉपर्टी का प्रकार बदलता है।
VALUE_INVALIDकोई डिफ़ॉल्ट या ओवरराइड मौजूद नहीं है, प्रॉपर्टी के प्रकार से मेल नहीं खाता, या 5 स्तरों से अधिक गहराई तक नेस्टेड है।
PROPERTIES_TOO_LARGEफ़्लैग के प्रॉपर्टी मान 10,000 बाइट्स से अधिक हैं।
RULES_LIMIT10 से अधिक नियम।
RULE_NOT_FOUNDrule_id फ़्लैग के नियमों में से कोई नहीं है।
PERCENT_INVALIDpercent_bp 0–10000 से बाहर है।
OVERRIDE_UNKNOWN_PROPERTYकोई ओवरराइड ऐसी प्रॉपर्टी बताता है जो फ़्लैग में नहीं है।
SEGMENT_NOT_FOUNDनियम का सेगमेंट मौजूद नहीं है या किसी अन्य एप्लिकेशन का है।
INVALID_SEGMENT_TYPEनियम के सेगमेंट में ऐसी शर्त है जिसका मूल्यांकन फ़्लैग नहीं कर सकते: इवेंट, स्टैटिक, एक्सटर्नल, लास्ट अपडेट या बेस्ट टाइम टू सेंड।
FLAG_DEPENDENCYनियम के सेगमेंट में फ़ीचर फ़्लैग की शर्त है, और कोई फ़्लैग किसी दूसरे फ़्लैग पर निर्भर नहीं हो सकता। Create, Update और Restore इसे लौटाते हैं, और सेगमेंट कोड filter_code में होता है।
CONFIRM_REQUIREDReshuffle को confirm: true के बिना भेजा गया।
TAG_CONFLICTअकाउंट में PW_FF_ के बाद फ़्लैग की वाले नाम का एक कस्टम टैग है।
FEATURE_FLAGS_NOT_ALLOWEDअकाउंट के प्लान में फ़ीचर फ़्लैग शामिल नहीं हैं।
FLAGS_LIMITएप्लिकेशन में उतने ही गैर-आर्काइव फ़्लैग हैं जितने प्लान अनुमति देता है।
VERSION_CONFLICTआपके भेजे गए version के बाद से फ़्लैग बदल गया है।
PAYLOAD_TOO_LARGEएप्लिकेशन के फ़्लैग एक डिवाइस के उत्तर में 64 KB से अधिक जगह लेंगे।
STATUS_CONFLICTस्टेटस ऑपरेशन की अनुमति नहीं देता, उदाहरण के लिए आर्काइव किए गए फ़्लैग को बंद करना।