{"definitions":{},"host":"api.notiflow.empushy.com","info":{"contact":{"email":"hello@empushy.com","name":"Kieran Fraser","url":"https://notiflow.empushy.com"},"description":"Social listening API for push notifications.","title":"NotiFlow API","version":"1.0.0"},"license":{"name":" CC BY-NC 4.0","url":"https://creativecommons.org/licenses/by-nc/4.0/deed.en"},"paths":{"/apps/by-package":{"get":{"description":"This endpoint allows you to retrieve enriched app-level data\nbased on a given appPackage (e.g., com.whatsapp).\nUseful when you want to enrich a notification or understand\nthe metadata behind a specific app.\n","parameters":[{"description":"API key used for authenticating the request.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Unique app package identifier (e.g. com.flashsale.app).","in":"query","name":"appPackage","required":true,"type":"string"}],"responses":{"200":{"content":{"application/json":{"example":{"appName":"FlashSaleApp","appPackage":"com.flashsale.app","category":"Shopping","downloads":3.2,"inAppPurchases":true,"installs":5000000,"pegi":"PEGI 3","reviews":13214,"stars":4.6,"website":"https://flashsale.app"}}},"description":"Metadata fields for the specified app."},"400":{"description":"Bad request \u2013 appPackage missing."},"404":{"description":"App not found in the database."}},"summary":"Get App Metadata by Package Name","tags":["apps"]}},"/apps/most-active":{"get":{"description":"This endpoint returns a ranked list of brands (mapped from app names) that sent\nthe highest number of notifications within the specified time range.\nIt is useful for identifying dominant players and notification volume leaders\nin a given genre or across the entire dataset.\n","parameters":[{"description":"API key used for authenticating the request.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Start date in YYYY-MM-DD format (default is 30 days ago).","format":"date","in":"query","name":"start_date","required":false,"type":"string"},{"description":"End date in YYYY-MM-DD format (default is today).","format":"date","in":"query","name":"end_date","required":false,"type":"string"},{"description":"Filter by app genre (e.g. Retail, Finance, Entertainment).","in":"query","name":"genre","required":false,"type":"string"}],"responses":{"200":{"description":"A list of the most active brands by notification volume."}},"summary":"Get Most Active Brands","tags":["apps"]}},"/content/behavioral-triggers":{"get":{"description":"This endpoint analyzes the first value in the `behavioral_triggers` array of each notification\nand returns a count of how often each trigger (e.g. \"FOMO\", \"Urgency\", \"Reward\", \"Curiosity\") appears.\nOnly documents with a valid value (not \"None\") are included.\nUseful for identifying behavioral nudges used by brands in their push notifications.\n","parameters":[{"description":"API key used for authenticating the request.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Start date in YYYY-MM-DD format (default is 30 days ago).","format":"date","in":"query","name":"start_date","required":false,"type":"string"},{"description":"End date in YYYY-MM-DD format (default is today).","format":"date","in":"query","name":"end_date","required":false,"type":"string"},{"description":"Filter by brand (maps to appName in the database).","in":"query","name":"brand","required":false,"type":"string"},{"description":"Filter by app genre (e.g. Retail, Finance, News).","in":"query","name":"genre","required":false,"type":"string"}],"responses":{"200":{"description":"A list of behavioral triggers and their usage counts."}},"summary":"Get Behavioral Trigger Distribution","tags":["content"]}},"/content/behavioral-triggers-by-hour":{"get":{"description":"This endpoint analyzes all values in the `behavioral_triggers` array of each notification\nand counts how often each trigger appears by hour (from 0 to 23). \nOnly documents with valid values are included.\n","parameters":[{"in":"header","name":"X-API-Key","required":true,"type":"string"},{"format":"date","in":"query","name":"start_date","type":"string"},{"format":"date","in":"query","name":"end_date","type":"string"},{"in":"query","name":"brand","type":"string"},{"in":"query","name":"genre","type":"string"}],"responses":{"200":{"description":"A list of (trigger, hour, count) dictionaries"}},"summary":"Get Behavioral Trigger Frequencies by Hour of Day","tags":["content"]}},"/content/call-to-emotion":{"get":{"description":"This endpoint analyzes the first value in the `call_to_emotion` array of each notification\nand returns a count of how often each emotional trigger (e.g. \"Urgency\", \"Fear\", \"Excitement\") appears.\nOnly documents with a valid value (not \"None\") are included.\nUseful for identifying emotional marketing strategies used by apps or brands.\n","parameters":[{"description":"API key used for authenticating the request.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Start date in YYYY-MM-DD format (default is 30 days ago).","format":"date","in":"query","name":"start_date","required":false,"type":"string"},{"description":"End date in YYYY-MM-DD format (default is today).","format":"date","in":"query","name":"end_date","required":false,"type":"string"},{"description":"Filter by brand (maps to appName in the database).","in":"query","name":"brand","required":false,"type":"string"},{"description":"Filter by app genre (e.g. Retail, Finance, News).","in":"query","name":"genre","required":false,"type":"string"}],"responses":{"200":{"description":"A list of emotional triggers and their usage counts."}},"summary":"Get Call-to-Emotion Distribution","tags":["content"]}},"/content/context-awareness-by-hour":{"get":{"description":"Counts occurrences of each value in the `context_awareness` array by hour (0-23).","parameters":[{"in":"header","name":"X-API-Key","required":true,"type":"string"},{"format":"date","in":"query","name":"start_date","type":"string"},{"format":"date","in":"query","name":"end_date","type":"string"},{"in":"query","name":"brand","type":"string"},{"in":"query","name":"genre","type":"string"}],"responses":{"200":{"description":"A list of (context, hour, count) dictionaries"}},"summary":"Get Context Awareness Frequencies by Hour of Day","tags":["content"]}},"/content/emotional-tone":{"get":{"description":"This endpoint analyzes the first value in the `emotional_tone` array of each notification\nand returns a count of how often each emotional tone appears. Only documents with a valid\ntone (non-\"None\") are included. Useful for measuring brand tone or emotional targeting\nacross campaigns and categories.\n","parameters":[{"description":"API key used for authenticating the request.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Start date in YYYY-MM-DD format (default is 30 days ago).","format":"date","in":"query","name":"start_date","required":false,"type":"string"},{"description":"End date in YYYY-MM-DD format (default is today).","format":"date","in":"query","name":"end_date","required":false,"type":"string"},{"description":"Filter by brand (maps to appName in the database).","in":"query","name":"brand","required":false,"type":"string"},{"description":"Filter by app genre (e.g. Retail, Finance, Entertainment).","in":"query","name":"genre","required":false,"type":"string"}],"responses":{"200":{"description":"A list of emotional tones and their counts."}},"summary":"Get Emotional Tone Distribution","tags":["content"]}},"/content/list-genre":{"get":{"description":"This endpoint retrieves all unique app genres present in the notification database.\nGenres represent app categories such as \"Retail\", \"Finance\", \"Entertainment\", \n\"Social Media\", \"Gaming\", etc. The list can be filtered by brand to see which \ngenres a specific brand operates in, or by date range to see genres that were \nactive during a particular time period. Useful for populating filter dropdowns,\nanalyzing market segments, and understanding content categorization.\n","parameters":[{"description":"API key used for authenticating the request.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Filter by brand (maps to appName in the database).","in":"query","name":"brand","required":false,"type":"string"},{"description":"Start date in YYYY-MM-DD format (default is 30 days ago).","format":"date","in":"query","name":"start_date","required":false,"type":"string"},{"description":"End date in YYYY-MM-DD format (default is today).","format":"date","in":"query","name":"end_date","required":false,"type":"string"}],"responses":{"200":{"description":"A list of unique genres available in the system."}},"summary":"    Get Genre List","tags":["content"]}},"/content/notification-by-hour-sample":{"get":{"parameters":[{"in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Comma-separated hours (0-23)","in":"query","name":"hours","required":true,"type":"string"},{"format":"date","in":"query","name":"start_date","type":"string"},{"format":"date","in":"query","name":"end_date","type":"string"},{"in":"query","name":"brand","type":"string"},{"in":"query","name":"genre","type":"string"}],"responses":{"200":{"description":"List of samples keyed by hour."}},"summary":"Get a recent sample notification for specified hours (local time).","tags":["content"]}},"/content/notification-delivery-by-hour":{"get":{"description":"Aggregates notifications by hour of day using the posted timestamp,\nreturning both raw counts and percentage of total volume.\n","parameters":[{"in":"header","name":"X-API-Key","required":true,"type":"string"},{"format":"date","in":"query","name":"start_date","type":"string"},{"format":"date","in":"query","name":"end_date","type":"string"},{"in":"query","name":"brand","type":"string"},{"in":"query","name":"genre","type":"string"}],"responses":{"200":{"description":"List of dictionaries with hour, count, and pct."}},"summary":"Get Notification Delivery Distribution by Hour of Day","tags":["content"]}},"/content/notification-length":{"get":{"description":"This endpoint calculates the length of each notification\u2019s text content and groups it\ninto predefined length ranges: \"0-49\", \"50-99\", \"100-149\", and \"150+\" characters.\nIt returns the count of notifications falling into each range. Useful for analyzing\ncopy density, message brevity, and notification formatting strategies.\n","parameters":[{"description":"API key used for authenticating the request.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Start date in YYYY-MM-DD format (default is 30 days ago).","format":"date","in":"query","name":"start_date","required":false,"type":"string"},{"description":"End date in YYYY-MM-DD format (default is today).","format":"date","in":"query","name":"end_date","required":false,"type":"string"},{"description":"Filter by brand (maps to appName in the database).","in":"query","name":"brand","required":false,"type":"string"},{"description":"Filter by app genre (e.g. Retail, Finance, Entertainment).","in":"query","name":"genre","required":false,"type":"string"}],"responses":{"200":{"description":"A list of length ranges and their notification counts."}},"summary":"Get Notification Length Distribution","tags":["content"]}},"/experiments/cte-variation":{"get":{"description":"<br/>This endpoint analyzes the `call_to_emotion` field to return the most common emotional tones<br/>(e.g., \"Urgency\", \"Curiosity\") along with their usage strength and top triggering phrases.<br/><br/>","parameters":[{"description":"API key used for authenticating the request.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Start date in YYYY-MM-DD format (defaults to 30 days ago)","format":"date","in":"query","name":"start_date","required":false,"type":"string"},{"description":"End date in YYYY-MM-DD format (defaults to today)","format":"date","in":"query","name":"end_date","required":false,"type":"string"},{"description":"Filter by app name (brand)","in":"query","name":"brand","required":false,"type":"string"},{"description":"Maximum number of top CTA values to return (default 10)","in":"query","name":"limit","required":false,"type":"integer"},{"description":"Number of top matched phrases to return for each CTA value (default 3)","in":"query","name":"sample_count","required":false,"type":"integer"}],"responses":{"200":{"content":{"application/json":{"example":{"brand":"BikeWale","end_date":"2024-06-19","start_date":"2024-06-01","top_cte_variations":[{"avg_strength":3.8,"count":42,"top_matches":[{"count":14,"match":"Breaking News"},{"count":10,"match":"Flash Sale"},{"count":7,"match":"Limited-time"}],"total_strength":112,"value":"Urgency"}]}}},"description":"A list of top call-to-emotion values and their stats"}},"summary":"Get top call-to-emotion (CTE) variations used in notifications.","tags":["experiments"]}},"/search/notification-text":{"get":{"description":"Searches the text content of notifications.\nReturns matching notifications with basic metadata. Useful for tracking themes,\ncampaign mentions, or specific keywords across mobile and web push messages.\n","parameters":[{"description":"API key used for authenticating the request.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Full-text query string (e.g., \"discount\", \"breaking news\").","in":"query","name":"q","required":true,"type":"string"},{"description":"Start date in YYYY-MM-DD format (default is 30 days ago).","format":"date","in":"query","name":"start_date","required":false,"type":"string"},{"description":"End date in YYYY-MM-DD format (default is today).","format":"date","in":"query","name":"end_date","required":false,"type":"string"},{"description":"Filter by brand.","in":"query","name":"brand","required":false,"type":"string"},{"description":"Filter by genre.","in":"query","name":"genre","required":false,"type":"string"},{"description":"Maximum number of results to return (default is 100).","in":"query","name":"limit","required":false,"type":"integer"}],"responses":{"200":{"description":"A list of matching notifications."}},"summary":"Search Notification Text","tags":["search"]}},"/trends/behavioral-triggers-by-brand":{"get":{"description":"Returns the most frequent behavioral triggers used by each brand, with their associated average strength scores. Can be filtered by brand and date range.\n","parameters":[{"description":"Filter by brand name (appName)","in":"query","name":"brand","required":false,"schema":{"type":"string"}},{"description":"Start date (YYYY-MM-DD)","in":"query","name":"start_date","required":false,"schema":{"format":"date","type":"string"}},{"description":"End date (YYYY-MM-DD)","in":"query","name":"end_date","required":false,"schema":{"format":"date","type":"string"}},{"description":"Maximum number of top behaviors per brand","in":"query","name":"limit","required":false,"schema":{"default":5,"type":"integer"}},{"description":"Your API key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"A list of top behavioral triggers per brand"}},"summary":"Get top behavioral triggers by brand","tags":["trends"]}},"/trends/daily-volume":{"get":{"description":"This endpoint returns a time series of daily notification counts across all brands,\noptionally filtered by brand name, brand genre, and date range.\n","parameters":[{"description":"API key used for authenticating the request.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Start date in YYYY-MM-DD format (default is 30 days ago).","format":"date","in":"query","name":"start_date","required":false,"type":"string"},{"description":"End date in YYYY-MM-DD format (default is today).","format":"date","in":"query","name":"end_date","required":false,"type":"string"},{"description":"Filter by specific brand name (e.g. com.spotify.music).","in":"query","name":"brand name","required":false,"type":"string"},{"description":"Filter by brand genre (e.g. Retail, Finance, Games).","in":"query","name":"genre","required":false,"type":"string"}],"responses":{"200":{"description":"A list of daily counts of notifications."}},"summary":"Get Daily Notification Volume","tags":["trends"]}},"/trends/discount-type":{"get":{"description":"This endpoint analyzes the first `discount_type` field in each notification\u2019s\n`specific_promotion_details` and returns the count of each unique promotion type\n(e.g. \"Flat Discount\", \"BOGO\"). Only notifications with a non-empty `discount_type.value`\nare included. Useful for analyzing promotional strategy trends over time.\n","parameters":[{"description":"API key used for authenticating the request.","in":"header","name":"X-API-Key","required":true,"type":"string"},{"description":"Start date in YYYY-MM-DD format (default is 30 days ago).","format":"date","in":"query","name":"start_date","required":false,"type":"string"},{"description":"End date in YYYY-MM-DD format (default is today).","format":"date","in":"query","name":"end_date","required":false,"type":"string"},{"description":"Filter by brand (maps to appName in the database).","in":"query","name":"brand","required":false,"type":"string"},{"description":"Filter by app genre (e.g. Retail, Finance, Entertainment).","in":"query","name":"genre","required":false,"type":"string"}],"responses":{"200":{"description":"A list of discount types and their counts."}},"summary":"Get Discount Type Distribution","tags":["trends"]}},"/trends/disruptive-apps":{"get":{"description":"<br/>This endpoint compares the number of notifications sent by each app in the<br/>last 7 days to the previous 7 days. It returns apps with the highest relative<br/>increases, prioritizing those that had no activity in the previous week.<br/><br/>The results are sorted as follows:<br/>1. Apps with 0 notifications in the previous 7 days and >0 in the last 7 days,<br/>   sorted by raw count in the last 7 days.<br/>2. Remaining apps sorted by their increase ratio (last_7_days / previous_7_days).<br/><br/>","parameters":[{"description":"Your API key.","in":"header","name":"X-API-Key","required":true,"type":"string"}],"responses":{"200":{"description":"A list of apps with recent notification activity spikes.","examples":{"application/json":{"results":[{"appName":"NewTrendingApp","increase_ratio":9999,"last_7_days":75,"previous_7_days":0},{"appName":"ConsistentApp","increase_ratio":5.0,"last_7_days":100,"previous_7_days":20}]}}},"401":{"description":"Unauthorized \u2013 API key missing or invalid."}},"summary":"Retrieve apps with the largest recent spikes in notification activity.","tags":["trends"]}},"/trends/top-emotional-triggers":{"get":{"description":"<br/>","parameters":[{"description":"Your API key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}},{"description":"Start date in YYYY-MM-DD format (defaults to 7 days ago)","in":"query","name":"start_date","schema":{"format":"date","type":"string"}},{"description":"End date in YYYY-MM-DD format (defaults to today)","in":"query","name":"end_date","schema":{"format":"date","type":"string"}},{"description":"Optional appName filter (brand)","in":"query","name":"brand","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"results":[{"count":1300,"emotion":"Urgency","example_matches":["now","hurry","limited"]}]}}},"description":"A list of top emotional triggers and their usage count."},"401":{"description":"Unauthorized \u2013 API key missing or invalid."}},"summary":"Retrieve the most common emotional triggers in recent notifications.","tags":["trends"]}},"/trends/urgency-index":{"get":{"description":"<br/>","parameters":[{"description":"Your API key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}},{"description":"Start date in YYYY-MM-DD format (defaults to 7 days ago)","in":"query","name":"start_date","schema":{"format":"date","type":"string"}},{"description":"End date in YYYY-MM-DD format (defaults to today)","in":"query","name":"end_date","schema":{"format":"date","type":"string"}},{"description":"Optional appName filter (brand)","in":"query","name":"brand","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"results":[{"appName":"FlashSaleApp","sample_notification":"Ends tonight! 50% off everything!","urgency_index":0.87}]}}},"description":"A list of apps with urgency scores and example notifications."},"401":{"description":"Unauthorized \u2013 API key missing or invalid."}},"summary":"Get apps ranked by their urgency in push notifications.","tags":["trends"]}},"/trends/weekend-whisper":{"get":{"description":"<br/>","parameters":[{"description":"Your API key","in":"header","name":"X-API-Key","required":true,"schema":{"type":"string"}},{"description":"Start date in YYYY-MM-DD format (defaults to 14 days ago)","in":"query","name":"start_date","schema":{"format":"date","type":"string"}},{"description":"End date in YYYY-MM-DD format (defaults to today)","in":"query","name":"end_date","schema":{"format":"date","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"results":[{"category":"Shopping","weekday_count":9432,"weekend_count":15234},{"category":"Games","weekday_count":12001,"weekend_count":9021}]}}},"description":"A list of categories with weekend vs. weekday volume counts."},"401":{"description":"Unauthorized \u2013 API key missing or invalid."}},"summary":"Get categories that ramp up notification volume on weekends.","tags":["trends"]}}},"schemes":["https"],"swagger":"2.0","tags":[{"description":"Endpoints related to scheduling notifications.","name":"Scheduling"}]}