{"openapi":"3.1.0","info":{"title":"Reddit CI API","description":"Read-only customer-intelligence data from Reddit (Sep 2025 – Aug 2026). Header `X-API-Key` required. Quota per key: 120 requests/minute, 5000 requests/day, 50000 result rows/day. Percentages are weighted; `n` = raw tagged posts.","version":"1.0"},"paths":{"/v1/health":{"get":{"summary":"Health","operationId":"health_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/usage":{"get":{"summary":"Your quota use today","operationId":"my_usage_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/categories":{"get":{"summary":"Categories","operationId":"categories_v1_categories_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/{cat}/overview":{"get":{"summary":"Headline numbers: verdicts, goals, triggers, objections, side effects, product types","operationId":"overview_v1__cat__overview_get","parameters":[{"name":"cat","in":"path","required":true,"schema":{"type":"string","title":"Cat"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/{cat}/brands":{"get":{"summary":"All brands: mentions in all posts, people, verdict share, side effects, trend","operationId":"brands_v1__cat__brands_get","parameters":[{"name":"cat","in":"path","required":true,"schema":{"type":"string","title":"Cat"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/{cat}/brands/{brand}":{"get":{"summary":"One brand: verdict, side effects, objections, segments, switches, quotes","operationId":"brand_v1__cat__brands__brand__get","parameters":[{"name":"cat","in":"path","required":true,"schema":{"type":"string","title":"Cat"}},{"name":"brand","in":"path","required":true,"schema":{"type":"string","title":"Brand"}},{"name":"quotes","in":"query","required":false,"schema":{"type":"integer","maximum":50,"default":10,"title":"Quotes"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/{cat}/compare":{"get":{"summary":"Brands side by side (comma-separated)","operationId":"compare_v1__cat__compare_get","parameters":[{"name":"cat","in":"path","required":true,"schema":{"type":"string","title":"Cat"}},{"name":"brands","in":"query","required":true,"schema":{"type":"string","title":"Brands"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/{cat}/segments":{"get":{"summary":"All segments with size and verdict","operationId":"segments_v1__cat__segments_get","parameters":[{"name":"cat","in":"path","required":true,"schema":{"type":"string","title":"Cat"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/{cat}/segments/{sid}":{"get":{"summary":"One segment: stats, portrait, 6-step journey, opportunity, quotes","operationId":"segment_v1__cat__segments__sid__get","parameters":[{"name":"cat","in":"path","required":true,"schema":{"type":"string","title":"Cat"}},{"name":"sid","in":"path","required":true,"schema":{"type":"string","title":"Sid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/{cat}/trends":{"get":{"summary":"Rising and fading ingredients or brands (mentions per 1,000 posts by month)","operationId":"trends_v1__cat__trends_get","parameters":[{"name":"cat","in":"path","required":true,"schema":{"type":"string","title":"Cat"}},{"name":"type","in":"query","required":false,"schema":{"type":"string","pattern":"^(ingredient|brand)$","default":"ingredient","title":"Type"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/{cat}/whitespace":{"get":{"summary":"Unmet-need themes with exact counts and product ideas","operationId":"whitespace_v1__cat__whitespace_get","parameters":[{"name":"cat","in":"path","required":true,"schema":{"type":"string","title":"Cat"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/{cat}/switches":{"get":{"summary":"Brand moves and reasons","operationId":"switches_v1__cat__switches_get","parameters":[{"name":"cat","in":"path","required":true,"schema":{"type":"string","title":"Cat"}},{"name":"brand","in":"query","required":false,"schema":{"type":"string","default":"","title":"Brand"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/{cat}/audience":{"get":{"summary":"People-level facts for all authors: gender, life stage, supplements, pets, activity","operationId":"audience_v1__cat__audience_get","parameters":[{"name":"cat","in":"path","required":true,"schema":{"type":"string","title":"Cat"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/{cat}/posts":{"get":{"summary":"Tagged posts with filters (text excerpt up to 600 chars, max 100 per page)","operationId":"posts_v1__cat__posts_get","parameters":[{"name":"cat","in":"path","required":true,"schema":{"type":"string","title":"Cat"}},{"name":"q","in":"query","required":false,"schema":{"type":"string","default":"","title":"Q"}},{"name":"brand","in":"query","required":false,"schema":{"type":"string","default":"","title":"Brand"}},{"name":"segment","in":"query","required":false,"schema":{"type":"string","default":"","title":"Segment"}},{"name":"verdict","in":"query","required":false,"schema":{"type":"string","default":"","title":"Verdict"}},{"name":"goal","in":"query","required":false,"schema":{"type":"string","default":"","title":"Goal"}},{"name":"trigger","in":"query","required":false,"schema":{"type":"string","default":"","title":"Trigger"}},{"name":"objection","in":"query","required":false,"schema":{"type":"string","default":"","title":"Objection"}},{"name":"date_from","in":"query","required":false,"schema":{"type":"string","default":"","title":"Date From"}},{"name":"date_to","in":"query","required":false,"schema":{"type":"string","default":"","title":"Date To"}},{"name":"relevant","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Relevant"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/{cat}/stats":{"get":{"summary":"Weighted distribution of any tag field, with optional filters (e.g. field=objections&segment=acne)","operationId":"stats_v1__cat__stats_get","parameters":[{"name":"cat","in":"path","required":true,"schema":{"type":"string","title":"Cat"}},{"name":"field","in":"query","required":true,"schema":{"type":"string","title":"Field"}},{"name":"segment","in":"query","required":false,"schema":{"type":"string","default":"","title":"Segment"}},{"name":"brand","in":"query","required":false,"schema":{"type":"string","default":"","title":"Brand"}},{"name":"goal","in":"query","required":false,"schema":{"type":"string","default":"","title":"Goal"}},{"name":"verdict","in":"query","required":false,"schema":{"type":"string","default":"","title":"Verdict"}},{"name":"top","in":"query","required":false,"schema":{"type":"integer","maximum":60,"default":25,"title":"Top"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/mentions":{"get":{"summary":"Count any term across all 78 M topic rows (supplements, skincare, pets), by month or community","operationId":"mentions_v1_mentions_get","parameters":[{"name":"term","in":"query","required":true,"schema":{"type":"string","title":"Term"}},{"name":"topic","in":"query","required":false,"schema":{"type":"string","pattern":"^(all|supp|skin|pet)$","default":"all","title":"Topic"}},{"name":"by","in":"query","required":false,"schema":{"type":"string","pattern":"^(month|subreddit)$","default":"month","title":"By"}},{"name":"date_from","in":"query","required":false,"schema":{"type":"string","default":"2025-09-01","title":"Date From"}},{"name":"date_to","in":"query","required":false,"schema":{"type":"string","default":"2026-08-31","title":"Date To"}},{"name":"top","in":"query","required":false,"schema":{"type":"integer","maximum":100,"default":30,"title":"Top"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/topics/search":{"get":{"summary":"Search all 78 M topic posts (supplements, skincare, pets): term, topic, community, layer, dates","operationId":"topic_posts_v1_topics_search_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","default":"","title":"Q"}},{"name":"topic","in":"query","required":false,"schema":{"type":"string","pattern":"^(all|supp|skin|pet)$","default":"all","title":"Topic"}},{"name":"subreddit","in":"query","required":false,"schema":{"type":"string","default":"","title":"Subreddit"}},{"name":"layer","in":"query","required":false,"schema":{"type":"string","pattern":"^(|core|problem|keyword)$","default":"","title":"Layer"}},{"name":"date_from","in":"query","required":false,"schema":{"type":"string","default":"2025-09-01","title":"Date From"}},{"name":"date_to","in":"query","required":false,"schema":{"type":"string","default":"2026-08-31","title":"Date To"}},{"name":"text_chars","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"default":600,"title":"Text Chars"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/topics/counts":{"get":{"summary":"Counts for any filter over the 78 M topic posts, grouped by month, subreddit, layer or topic","operationId":"topic_stats_v1_topics_counts_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","default":"","title":"Q"}},{"name":"topic","in":"query","required":false,"schema":{"type":"string","pattern":"^(all|supp|skin|pet)$","default":"all","title":"Topic"}},{"name":"subreddit","in":"query","required":false,"schema":{"type":"string","default":"","title":"Subreddit"}},{"name":"layer","in":"query","required":false,"schema":{"type":"string","pattern":"^(|core|problem|keyword)$","default":"","title":"Layer"}},{"name":"by","in":"query","required":false,"schema":{"type":"string","pattern":"^(month|subreddit|layer|topic)$","default":"month","title":"By"}},{"name":"date_from","in":"query","required":false,"schema":{"type":"string","default":"2025-09-01","title":"Date From"}},{"name":"date_to","in":"query","required":false,"schema":{"type":"string","default":"2026-08-31","title":"Date To"}},{"name":"top","in":"query","required":false,"schema":{"type":"integer","maximum":200,"default":50,"title":"Top"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/topics/communities":{"get":{"summary":"Communities by topic volume (12 months)","operationId":"topic_subreddits_v1_topics_communities_get","parameters":[{"name":"topic","in":"query","required":false,"schema":{"type":"string","pattern":"^(all|supp|skin|pet)$","default":"all","title":"Topic"}},{"name":"top","in":"query","required":false,"schema":{"type":"integer","maximum":500,"default":100,"title":"Top"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/audience":{"get":{"summary":"Who writes about X: where they spend time on Reddit (lift vs all topic authors), group level only","operationId":"audience_q_v1_audience_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","title":"Q"}},{"name":"topic","in":"query","required":false,"schema":{"type":"string","pattern":"^(all|supp|skin|pet)$","default":"all","title":"Topic"}},{"name":"min_people","in":"query","required":false,"schema":{"type":"integer","minimum":10,"default":30,"title":"Min People"}},{"name":"top","in":"query","required":false,"schema":{"type":"integer","maximum":200,"default":50,"title":"Top"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}