Documentation Index
Fetch the complete documentation index at: https://docs.upriver.ai/llms.txt
Use this file to discover all available pages before exploring further.
Changelog
Stay up to date with the latest changes to the Upriver API.May 2026
Creator API: Creator Search — Pagination, Follower Bucket, and Category Filters
/v1/creators/search is now available. Use follower_bucket parameter (e.g. 10k_50k, 100k_500k) to browse creators by follower tier; and a free-text categories field automatically resolves search terms to category filters.April 2026
Creator API: Associated Creator Relationships
Creator responses now include anassociated_creators array. Each entry contains a stable creator_id and a creator_role (surface, primary_creator, group, member, or peer) describing how the creators are related across the platform.Trends API: Commercial Music Filter
POST /v2/trends/broad now accepts commercial_music_status=approved to limit results to sound trends explicitly cleared for commercial and business use.Trends API: Duplicate Trend Deduplication
Fixed same-sound trends appearing as multiple distinct entries in/v2/trends/broad; same-sound rows are now correctly merged before results are published. AI-effect trend families are also better consolidated, reducing near-duplicate trend entries.Creator API: Relative Metrics Category Accuracy
Fixedinclude=relative_metrics benchmarking a creator’s channel against the wrong category cohort on warm cache hits.Sponsors API: Publication Category Labels
Fixedpublication_categories returning empty in /v1/sponsors and /v1/sponsorships responses even when category data was present.Creator API: Enrichment Key Presence
Restored the key-presence contract forbio, audience, and brand_safety — these keys are now absent (rather than present with null values) when enrichment is unavailable for small-follower creators.Trends API: emerging Sort Replaces newest
/v2/trends/broad now accepts sort_by=emerging in place of the previously introduced sort_by=newest. The emerging sort surfaces trends at the moment they cross from noise to signal — ranked by when they first accumulated enough confirmed video evidence to look like a real trend. Update any calls using sort_by=newest to use sort_by=emerging; existing pagination cursors from newest results are also invalidated.Creator API: Enrichment Coverage Status
Thebio, audience, and brand_safety enrichment blocks now include a status field (full_coverage, limited_coverage, no_coverage) indicating how much evidence backed the result — helping callers distinguish confident findings from inconclusive ones.Brand API: /v1/brand Endpoint Removed
The deprecated /v1/brand endpoint has been removed. Use /v1/brand/research instead.Sponsors API: Expanded Default Sponsor Types
/v1/sponsors, /v1/sponsors/search, and /v1/sponsorships now include implicit_ad and affiliate in the default sponsor_types set. Previously, only explicit_ad, promotion, and unknown were returned when the parameter was omitted. Pass sponsor_types explicitly to restrict results to specific types.Trends API: newest Sort for Broad Trends
/v2/trends/broad now accepts sort_by=newest to surface trends most recently activated in the API, ranked by latest published video activity.Sponsorships API: Scope Filter Now Required
/v1/sponsorships (GET and POST) now requires at least one of sponsor_name, brand_id, publication_url, or categories. Requests with no scope filters now return HTTP 400.Products API: brand_url Required on All Requests
brand_url is now required on all /v1/brand/products requests, including pagination requests that supply a cursor. Previously, brand_url could be omitted when paginating.Creator API: Engagement Metrics Reliability
Improved reliability of engagement metrics for creator profiles.Trends API: Singular Tag Parameter Aliases
/v2/trends/broad now accepts tag and exclude_tag as aliases for the tags and exclude_tags parameters, and accepts a bare string in addition to an array for both fields.Creator API: General Keyword Search
/v1/creators/search now accepts a query parameter for name and keyword-based creator discovery — no URL required. Supports filtering by platforms, category_ids, follower range, creator_country, and creator_language. Results include score and match_signals ranking metadata.Products API: App Store Support
/v1/brand/products now supports Apple App Store and Google Play URLs, returning a structured product entry with the app’s name, description, price, and developer without requiring a full brand search.Products API: Input Validation and brand_name Deprecation
The brand_name parameter on /v1/brand/products is deprecated — brand name is now always resolved automatically from the URL for better accuracy. Marketplace, social media, and other non-brand URLs now return HTTP 400 immediately.Trends API: sort_by Parameter for Broad Trends
/v2/trends/broad now accepts a sort_by parameter: recommended (default, ranked by relevance and engagement) and timeliness to prioritize freshest currently-rising trends. The alias freshness is also accepted.Audience Insights: purchase_motivations Field
/v3/audience_insights persona segments now include a purchase_motivations field — the enduring outcomes, problems solved, and identity payoffs that drive the segment’s interest in the product category. This complements the existing purchase_triggers and purchase_barriers fields.Sponsors API: Date Filtering
/v1/sponsors and /v1/sponsors/search now accept days_back (1–365, default 90), since (YYYY-MM-DD), and until (YYYY-MM-DD) parameters for filtering by sponsorship date range, matching the existing parameters on the sponsorships endpoints.Sponsors API: industries Parameter Removed
The deprecated industries filter has been removed from /v1/sponsors and /v1/sponsors/search. Use categories instead.Products API: Configurable Result Limit
/v1/brand/products now accepts a limit parameter (5–20, default 10) to control how many products are returned per request. Per-result credit pricing is now active at 1.2 credits per product with a 5-credit minimum per request.Usage API: Custom Date Range
GET /v1/usage now accepts optional start_date and end_date query parameters (YYYY-MM-DD) to retrieve usage data for a specific date range.March 2026
Audience Insights: v3 Grounded Segments
/v3/audience_insights now returns two new fields per segment — communities (online spaces where the segment gathers) and buying_mindset (plain observations about purchasing behavior) — replacing the earlier fictional persona format with grounded audience intelligence. The personality_traits field is deprecated and now returns an empty array.Sponsors API: newsletter Platform Alias
The platforms filter on /v1/sponsors/search and /v1/sponsorships/search now accepts "newsletter" as a convenience alias, automatically expanding to Substack, Beehiiv, and Ghost publications.API: Authenticated Rate Limit Increase
Authenticated API requests are now rate-limited at 2,000 requests per 5 minutes, up from 300.Audience Insights: v2 Endpoint Deprecated
/v2/audience_insights is now deprecated; use /v3/audience_insights instead.Products API: Simplified Input Contract
/v1/brand/products now requires brand_url and returns brand_name in responses; the auto free-text input has been removed from both /v1/brand/products and /v1/brand/research. The legacy /v1/product endpoint has been removed.Creator API: Relative Engagement Benchmarks
Creator endpoints now supportinclude=relative_metrics to see how a creator’s engagement compares to peers in the same category and follower bucket. Returns per-channel engagement benchmarks with a band of bottom_25, mid_50, or top_25, along with the cohort details used for the comparison.Creator API: channel_relationship Field
The channels[].relationship_type field has been replaced by channels[].channel_relationship with clearer semantics. Primary channels are omitted (no field); secondary channels are now "attached" (a distinct show, brand, or project surface) or "group" (a shared or collab surface). The old relationship_type values (owner, shared_owner, member_of_group) are no longer returned.Sponsors API: sort_by Parameter
POST /v1/sponsors/search now accepts a sort_by parameter. The default total_ads ranks brands by most placements; recent ranks by most recent ad date instead.Usage API: Clarified Credit Fields
TheUsageByFeature object in usage responses has been updated for clarity: credit_cost is renamed to credit_rate (the per-result credit multiplier), usage is renamed to quantity (the raw count of items delivered), and a new credits_used field is added showing the total credits charged (quantity × credit_rate).Creator API: Stable Creator ID Redirects
When a stored creator ID has been merged into another creator,GET /v1/creators/{creator_id} now returns HTTP 200 with the canonical creator, a redirect object in the body (requested_creator_id, canonical_creator_id, reason), and an X-Creator-Redirect response header — clients should update any stored ID to redirect.canonical_creator_id. Stable creator IDs are also now returned in /v1/creators/search results when include=creator_id is specified.Trends API: content_structure Field and Filter
Trend responses now include a content_structure field indicating the shared non-audio pattern across videos: none (sound-led only), loose (shared theme or aesthetic without a repeatable template), or structured (repeatable text, editing, or visual template). The trends list endpoint now accepts content_structure as a filter parameter.Creator API: Comma-Separated include Values
Creator endpoints now accept comma-separated include values (e.g., include=engagement_metrics,bio) in addition to repeated query parameters.Creator API: Batch Endpoint Cross-Platform Coverage
Fixed/v1/creators/batch returning incomplete single-platform profiles when the stored record was sparse — batch lookups now fall through to live research and return complete cross-platform profiles, matching single-creator lookup behavior. Labels are also now returned correctly on cached batch hits.Sponsors API: brand_name Hint for Brand-URL Search
POST /v1/sponsors/search now accepts an optional brand_name field alongside brand_url. Supplying the brand name improves category classification accuracy when discovering sponsors by URL.Creator API: Video Inventory Metrics
include=video_metrics now derives upload frequency from a dedicated trailing 12-week inventory window instead of the recent engagement sample. Responses include new lookback_weeks, weeks_observed, and window_complete fields.Breakout Topics: Search Result Fields
Fixedrelevance_score and computed_status returning null or stale values in search results — both now reflect live scoring consistent with the list endpoint.Creator API: By-ID Endpoint Include Parity
GET /v1/creators/{creator_id} now supports all include values (engagement_metrics, video_metrics, bio, audience, brand_safety), matching GET /v1/creators?url=. Requests with invalid URLs now return HTTP 400 immediately instead of timing out.Trends API: uses_specific_sound Field
Trend responses now include a uses_specific_sound boolean indicating whether a trend requires a specific audio clip, making it easier to filter by creative flexibility.Trends API: Complete Video Sample Metadata
Fixed the trend detail endpoint strippingpublished_at and duration_seconds from video_samples. Both fields are now returned correctly.Breakout Topics: Citation Rate
Topic detail responses now include acitation_rate field — a daily breakdown of citation counts for charting topic momentum over time.Breakout Topics: Narratives
Breakout topics can now be grouped into narratives — storylines that connect related topics across angles and time.Trends API: New Filters
Added three new filter parameters:timeliness_status to control trend freshness (recent, active, stale), brand_safety for brand suitability filtering, and topic_scope to filter by how transferable a trend is (universal, niche, event_specific, person_specific).Trends API: Updated Response Fields
content_format has been replaced by participation_type (open, timed, lip_sync, choreography) with new topic_scope and content_scenarios response fields. Fields origin, virality_reason, brand_categories, and audience_vibes have been removed from trend responses.February 2026
Creator API: Audience Demographics Schema
Audience age data now uses structuredmin_age/max_age integers instead of string ranges, and the interests field has been removed from audience responses. Geography segments now include a country_name field alongside the ISO code.Creator API: Audience Demographics
Audience demographics are now available on all creator endpoints viainclude=audience. Returns directional signals for age, gender, geography, languages, and interests.Creator API: Stable Creator IDs
Creator endpoints now supportinclude=creator_id to return a stable Upriver creator ID. Use this ID with GET /creators/{creator_id} to reference the same creator across sessions without re-resolving URLs.Trends API: Content Filtering
Improved content filtering for trend recommendations.Audience Insights: Search and Citation Quality
Improved search relevance and citation quality for audience insights.Creator API: Audience Demographics Accuracy
Improved accuracy of creator audience demographic data.Brand Research: Brand Color Extraction
Improved accuracy of brand color extraction.Breakout Topics: Keyword Search Accuracy
Improved accuracy of breakout topics keyword search with better stemming, so queries return more relevant results.Breakout Topics: Entities
Addedinclude=entities parameter to breakout topics. Returns named entities (people, organizations, places) extracted from each topic, ranked by mention frequency with fine-grained Wikidata type classifications.Creator API: Brand Safety Advisories
Brand safetyflags have been renamed to advisories in API responses. Advisories now include inline citation markers with source attribution.Trends API: Sound Attribute Filters
The trends list endpoint now supports filtering by sound attributes for more targeted trend discovery.Breakout Topics: Improved Grouping
Related breakout topics are now grouped together, making it easier to follow a story across multiple angles.Creator API: Brand Safety
Brand safety analysis is now available for creators.Creator API: Terminated Account Filtering
Terminated creator accounts are now automatically excluded from API responses.Creator API: Engagement Metrics Latency
Engagement metrics now return significantly faster.Trends API: Sound Duration Fields
Trend responses now include asound_duration field.Creator API: YouTube Data Freshness
Fixed an issue where YouTube creator follower counts could become stale and fail to refresh automatically.Audience Dimensions: Rate Limiting
Added per-user rate limiting to the/v1/audience_dimensions endpoint to ensure fair usage and system stability.Creator API: Enhanced Video Metrics
Creator video metrics now includepct_over_8m field showing the percentage of videos exceeding 8 minutes, useful for identifying long-form content creators. Also improved gaming category classification accuracy.Creator API: Real-Time Follower Counts
Creator API now refreshes stale subscriber and follower counts at request time, ensuring you always get current audience size data.Creator API: Video Metrics Enrichment
Addedinclude=video_metrics parameter to creator endpoints. Get video duration and upload frequency data to estimate ad inventory opportunities.Audience Insights v3
New/v3/audience_insights endpoint with improved audience segmentation, simplified calling (just pass a brand_url instead of chaining endpoints), and a configurable effort parameter for faster or deeper analysis.Creator API: Twitch Metadata
Improved Twitch metadata in API responses.TikTok Trends: Enhanced Metadata
Trends API responses now includetags and trend_type fields for better trend categorization and filtering.Trends API: Duration Filtering
Added duration filtering to trends endpoints. Filter TikTok trends by video length to find content that matches your target format.Breakout Topics: Politics Vertical
Added Politics vertical to breakout topics filtering. Use the/v1/breakout/metadata endpoint to discover available verticals including the new Politics category.Trends API: Expanded Trend Types
Trends endpoints now support additional trend type classifications for more granular filtering and discovery.Trends API: Individual Trend Lookup
New GET/v1/trends/{trend_id} endpoint to retrieve a specific trend by ID with full trend details.Trends API: Optional Playback URLs
Addedinclude=playback parameter to trend endpoints. Audio playback URLs are now fetched on demand rather than included by default, reducing response times when playback data isn’t needed.Trends Search: Enhanced Metadata
Trends search results now include complete trend metadata (engagement stats, example videos, audio details) for richer context without requiring additional API calls.Breakout Topics: Citation Quality
Improved citation quality with better deduplication of wire service articles across topics.Breakout Topics: Improved Sorting Control
Replaceduse_dynamic_scoring boolean with sort_by enum parameter. Choose 'relevance' for time-sensitive trending topics or 'importance' for stable base scores.Breakout Topics: Metadata Endpoint
New/v1/breakout/metadata endpoint for discovering available verticals and categories to filter breakout topics.Breakout Topics: Field Rename
Renamedcanonical_name to topic_name in breakout topics responses. The old canonical_name field remains available but is deprecated.Creator API: Bio Enrichment
Creator profiles now include biographical summaries. Useinclude=bio to get a concise summary of the creator’s background and content focus.January 2026
Creator API: Enhanced Profile Data
Creator API responses now include enriched profile metadata and primary publication identifiers for better creator identification and categorization.TikTok Trends: Improved Video Relevance
Better video relevance scoring for more accurate trend recommendations.API Performance Improvements
- 3x speed improvement to the
/v1/audience_dimensionsendpoint - Faster response times for
/v1/trends/broadendpoint - Improved YouTube channel resolution performance
Creator API: Duplicate Profiles
Fixed an issue where the same YouTube channel could appear multiple times in search results.Breakout Topics: Multi-Label Classification
Topics can now be tagged with multiple labels simultaneously, enabling more nuanced topic categorization and filtering.Breakout Topics: Relevance and Momentum Tracking
Renameddynamic_score to relevance_score for clarity. Added trend object to topic responses showing momentum indicators like velocity and acceleration for better understanding of topic trajectory.Breakout Topics: Enhanced Signal Quality
- Improved Reddit signal filtering to exclude routine discussion threads
- Added engagement scores to topic responses for better signal assessment
- Expanded sports coverage in topic monitoring
Breakout Topics: Volume-Aware Momentum
Topic momentum scoring now adapts to conversation volume, providing more accurate trending signals across topics of different scales.Creator API: Labels and Tags
Addedlabels field to Creator API responses with stable category classifications. Labels use the same taxonomy as media_categories for consistent categorization across the platform. The existing tags field continues to provide flexible, free-form tagging.Breakout Topics: Improved Scoring
Better topic scoring with improved decay functions that adapt to the nature and popularity of each topic.Breakout Topics: Citations
Addedinclude_citations parameter to the breakout topics endpoint. When enabled, returns source URLs for each detected topic.Breakout Topics: Quality Improvements
- More accurate topic deduplication
- More accurate citation attribution
- Added engagement scoring for better signal quality
Brand Research API
Brand research endpoints consolidated to the v1 API path.Creator API: Performance
Major API performance improvements, especially for creators not previously tracked in our database.Breakout Topics API
New API for discovering emerging trending topics across news and social media.Audience Dimensions API
New/v1/audience_dimensions endpoint for structured audience profiling.Creator Batch Endpoint
New/v1/creators/batch endpoint for bulk creator lookups.Creator API: GET Endpoint
New GET/v1/creators endpoint for simplified creator lookups.Creator API: Engagement Metrics
Creator responses now include engagement metrics such as average views, likes, and comments across platforms. Metrics are computed from recent content and cached for performance.Creator API: Categories
Creator search results now include media categories and taxonomy classification.December 2025
Trends Search API
New trend search endpoint for finding relevant TikTok trends by keyword.Sponsors Search API
New/v1/sponsors/search and /v1/sponsorships/search endpoints. Search by brand URL for sponsorship data.Per-Result Pricing
Flexible per-result billing for products, sponsors, and trends endpoints.November 2025
Product Research API
Improved product deduplication and filtering. Brand name search support for sponsors.Products API: Enhanced Search
Parallel search mode using multiple data providers. Response caching for faster lookups.Products API: Pagination
Added cursor-based pagination for products endpoint. Improved product result ranking.Categories Search API
New/v1/categories/search endpoint to explore media categories.Trends Matching API
New/v1/trends/match endpoint to find relevant TikTok trends for brands.Creator Search API
New/v1/creators/search endpoint to discover creators. Cross-platform profile resolution for YouTube, Instagram, TikTok, Twitter, and Twitch. Includes subscriber counts and profile metadata.Brand Research API
New/v1/brand/research endpoint for comprehensive brand intelligence. Returns brand overview, target audience, and positioning.October 2025
Audience Insights v2: Personas
New/v2/audience_insights endpoint with improved persona generation. Includes personality traits and behavioral insights. Separate citations endpoint for source attribution.Sponsors API: Enhanced Data
Added brand domain and LinkedIn URL to sponsor responses.Categories API
New/v1/categories endpoint to browse the media category taxonomy.Sponsors API: Performance
Major performance improvements for sponsor and sponsorship lookups.TikTok Trends: Scoring
Enhanced trend scoring with engagement metrics. Audio and video quality scoring.September 2025
Products API
New/v1/brand/products endpoint to discover products from brand websites.TikTok Trends API
New/v1/trends/broad endpoint for discovering trending TikTok content. Audio and video trend samples with usage instructions. Pagination support.Sponsor Discovery API
New/v1/sponsors endpoint to discover brands sponsoring content. New /v1/sponsorships endpoint for detailed sponsorship data. Industry and URL-based filtering.