# llms.txt Source: https://docs.upriver.ai/ai/llmstxt Documentation index for LLMs and AI tools The [llms.txt file](https://llmstxt.org) is an industry standard that helps LLMs index content more efficiently, similar to how a sitemap helps search engines. AI tools can use this file to understand the Upriver documentation structure and find content relevant to user queries. Upriver hosts an `llms.txt` file at the root of the documentation site that lists all available pages. This file is always up to date and requires no maintenance. View the Upriver llms.txt at: [docs.upriver.ai/llms.txt](https://docs.upriver.ai/llms.txt) ## llms.txt structure An `llms.txt` file is a plain Markdown file that contains: * **Site title** as an H1 heading. * **Structured content sections** with links and a description of each page in the documentation. ```md Example llms.txt theme={null} # Upriver API Docs ## API Reference - [Brands](https://docs.upriver.ai/api-reference/brands): Search and retrieve brand data - [Creators](https://docs.upriver.ai/api-reference/creators): Look up creator profiles - [Audiences](https://docs.upriver.ai/api-reference/audiences): Analyze audience insights ``` This structured approach allows LLMs to efficiently process the documentation at a high level and locate relevant content for user queries. ## llms-full.txt The `llms-full.txt` file combines the entire Upriver documentation site into a single file as context for AI tools. View the Upriver llms-full.txt at: [docs.upriver.ai/llms-full.txt](https://docs.upriver.ai/llms-full.txt) # skill.md Source: https://docs.upriver.ai/ai/skillmd Give your AI agent the Upriver API reference The [`skill.md`](https://docs.upriver.ai/skill.md) file is a structured, machine-readable API reference that tells AI agents what they can do with the Upriver API. It follows the [skill.md specification](https://agentskills.io/specification) and includes endpoint descriptions, required parameters, and usage guidance in a format LLMs can reliably work with. View the Upriver skill.md at: [docs.upriver.ai/skill.md](https://docs.upriver.ai/skill.md) Both `skill.md` and `llms.txt` help agents work with the Upriver API, but they serve different purposes. * `skill.md` is a **capability summary**. It tells agents what actions are available, what inputs they need, and what constraints apply. * `llms.txt` is a **documentation index**. It lists available pages with descriptions so agents know where to find information. Use `skill.md` when you want agents to call the API directly. Use `llms.txt` when you want agents to browse the docs. ## Use skill.md with agents ### Skills CLI Agents can process the skill.md with the [skills CLI](https://www.npmjs.com/package/skills). ```bash theme={null} npx skills add https://docs.upriver.ai ``` ### Claude Code / OpenClaw Add the URL to your project context or reference it in a prompt: ```bash theme={null} curl -s https://docs.upriver.ai/skill.md >> AGENTS.md ``` ``` Use the Upriver API as described in https://docs.upriver.ai/skill.md ``` ### Cursor / Windsurf Add it as a doc in your project settings: 1. Go to **Settings → Docs** 2. Add `https://docs.upriver.ai/skill.md` ### ChatGPT / Claude.ai Paste the URL or file contents into your conversation: ``` Here's the API reference: https://docs.upriver.ai/skill.md Use it to help me call the Upriver API. ``` ### Any agent or framework Fetch it at build time or runtime: ```bash theme={null} curl -s https://docs.upriver.ai/skill.md ``` The file is plain Markdown. Works anywhere that accepts text context. ## What's in the file The skill.md includes: * **Metadata**: API name, description, and base URL. * **Authentication**: How to authenticate requests. * **Endpoints**: Available actions organized by resource (brands, creators, audiences, trends, etc). * **Parameters**: Required and optional inputs for each endpoint. * **Usage guidance**: Tips on how to chain endpoints and handle responses. # Get Usage Source: https://docs.upriver.ai/api-reference/account/get-usage /api-reference/openapi.json get /v1/usage Get usage for the provided API key # Dimensions Source: https://docs.upriver.ai/api-reference/audience/dimensions /api-reference/openapi.json post /v1/audience_dimensions Extract atomic audience dimensions for a brand. Dimensions are the building blocks of personas. Returns granular behavioral, motivational, and lifestyle dimensions about relevant audiences for a specified brand. Each fact can be used for matching with user profiles. **Verbosity** controls fact phrasing (applies only to the `fact` field): - `verbose`: Full sentences with subject (e.g., 'This audience seeks healthy recipes') - `standard` (default): Phrases without subject (e.g., 'seeks healthy recipes') - `compact`: Keywords only (e.g., 'healthy recipes') **Response includes:** - Audience dimensions with classification and confidence scores - Supporting evidence snippets (optional) # Personas Source: https://docs.upriver.ai/api-reference/audience/personas /api-reference/openapi.json post /v2/audience_insights Get detailed audience personas with psychographics, behaviors, motivators, and barriers. Ideal for creative strategy, targeting, and understanding your audience at a psychological level. **Input:** Provide brand info, products, and industry context. Can chain output from Brand Research endpoint. **Output:** 3-5 distinct personas with personality traits, behavioral patterns, motivations, and barriers. **Citations Mode:** - `async` (recommended): Fast response, fetch citations separately via continuation token - `sync`: Include citations in response (slower) - `none`: No citations (fastest) # Personas - Citations Source: https://docs.upriver.ai/api-reference/audience/personas--citations /api-reference/openapi.json get /v2/audience_insights/{continuation_token}/citations Retrieve citations and behavioral evidence for audience personas. Use the continuation token from the `v2/audience_insights` response. **Recommended Usage:** Set `citations_mode=async` in the audience insights request, then call this endpoint to retrieve citations separately. This keeps the initial response fast while allowing deep citation analysis. # Personas (v3) Source: https://docs.upriver.ai/api-reference/audience/personas-v3 /api-reference/openapi.json post /v3/audience_insights Get detailed audience personas for a brand. **Input:** Brand URL, optional query and effort level. **Output:** Personas with purchase triggers, barriers, behaviors, language patterns, and optional real world citations. # Brand Research Source: https://docs.upriver.ai/api-reference/brands/brand-research /api-reference/openapi.json post /v1/brand/research Provides details for a brand including identity, target audience, and brand language. Returns structured data optimized for chaining into the Audience Insights endpoint. **Input Options:** - Provide `brand_name` and/or `brand_url` # Get Private Breakout Feed Source: https://docs.upriver.ai/api-reference/breakout-feeds/get-private-breakout-feed /api-reference/openapi.json get /v1/breakout/feeds/{feed_slug} # List Private Breakout Feeds Source: https://docs.upriver.ai/api-reference/breakout-feeds/list-private-breakout-feeds /api-reference/openapi.json get /v1/breakout/feeds # Find Similar Topics Source: https://docs.upriver.ai/api-reference/breakout-topics/find-similar-topics /api-reference/openapi.json post /v1/topics/breakout/similar Find topics similar to a given topic by embedding similarity. # Get Breakout Entity Source: https://docs.upriver.ai/api-reference/breakout-topics/get-breakout-entity /api-reference/openapi.json get /v1/entities/{entity_id}/breakout Get one entity's current breaking topics and a coarse timeline. # Get Breakout Topic Source: https://docs.upriver.ai/api-reference/breakout-topics/get-breakout-topic /api-reference/openapi.json get /v1/topics/breakout/{topic_id} Get a single breakout topic by ID. # Get Breakout Topics Metadata Source: https://docs.upriver.ai/api-reference/breakout-topics/get-breakout-topics-metadata /api-reference/openapi.json get /v1/topics/breakout/metadata Get metadata about available verticals and categories for filtering. Returns the taxonomy of verticals and their associated categories, with human-readable display names for building filter UIs. # Get Narrative Source: https://docs.upriver.ai/api-reference/breakout-topics/get-narrative /api-reference/openapi.json get /v1/topics/breakout/narratives/{narrative_id} Get a narrative by ID with member topics. # Get Topic Story View Source: https://docs.upriver.ai/api-reference/breakout-topics/get-topic-story-view /api-reference/openapi.json get /v1/topics/breakout/{topic_id}/story Get the best available derived story surface around a seed topic. # List Breakout Entities Source: https://docs.upriver.ai/api-reference/breakout-topics/list-breakout-entities /api-reference/openapi.json get /v1/entities/breakout List breaking entities (players or teams) for a vertical. # List Breakout Entity Tags Source: https://docs.upriver.ai/api-reference/breakout-topics/list-breakout-entity-tags /api-reference/openapi.json get /v1/entities/breakout/tags List the tags available to filter the breakout entity list by. # List Breakout Topics Source: https://docs.upriver.ai/api-reference/breakout-topics/list-breakout-topics /api-reference/openapi.json get /v1/topics/breakout List breakout topics with optional filters. Returns topics ranked by the specified sort mode (recommended / rising / top / newest); see the sort_by parameter. Legacy relevance/importance still work. # List Narratives Source: https://docs.upriver.ai/api-reference/breakout-topics/list-narratives /api-reference/openapi.json get /v1/topics/breakout/narratives List narrative arcs, ordered by most recently updated. # Search Breakout Topics Source: https://docs.upriver.ai/api-reference/breakout-topics/search-breakout-topics /api-reference/openapi.json post /v1/topics/breakout/search Search breakout topics using hybrid vector + keyword search. Supports three search modes: - vector: Semantic similarity search using embeddings - keyword: Full-text search using PostgreSQL tsvector - hybrid: Combined vector and keyword search (default) # Batch Creator Details Source: https://docs.upriver.ai/api-reference/creators/batch-creator-details /api-reference/openapi.json post /v1/creators/batch Provides creator profile information for multiple creators in a single request. Returns associated channels and labels for each URL. **Input:** Provide 1-10 social media profile URLs (e.g., https://youtube.com/@handle) **Note:** Engagement metrics are not available for batch requests. # Creator Profile by ID Source: https://docs.upriver.ai/api-reference/creators/creator-profile-by-id /api-reference/openapi.json get /v1/creators/{creator_id} Lookup a creator profile by Upriver creator ID. Returns the same payload shape as `GET /v1/creators` (URL lookup). The only difference is the lookup key (`creator_id` vs `url`). If the ID has been merged into another creator, the response includes a `redirect` object in the JSON body and the `X-Creator-Redirect` header. Clients should update any stored creator ID to `redirect.canonical_creator_id`. Use `include` for optional expansions. # Creator Profile by URL Source: https://docs.upriver.ai/api-reference/creators/creator-profile-by-url /api-reference/openapi.json get /v1/creators Lookup a creator profile by known social profile URL. Returns the same payload shape as `GET /v1/creators/{creator_id}`. The only difference is the lookup key (`url` vs `creator_id`). Use this endpoint when you have a channel/profile URL and do not yet have a stored `creator_id`. Use `include` for optional expansions. # Find Similar Creators (Beta) Source: https://docs.upriver.ai/api-reference/creators/find-similar-creators-beta /api-reference/openapi.json post /v1/creators/similar Find canonical creators who make content similar to an anchor creator. Provide either a `creator_id` returned by another creator endpoint for similarity across that creator's eligible channel cluster, or a known `channel_url` for channel-specific similarity. Each result may qualify through one coherent channel expression; every channel in a creator cluster does not need to match. Default ordering emphasizes shared niche and subject plus specific profession or life-role identity, with reach used only to separate otherwise close peers. Optional platform, category, reach, and country controls constrain which peers may appear. An empty `results` list is a complete answer; `incomplete_results` is true only when an internal time budget truncated the evaluation and a retry may return more. The first returned channel is the channel that qualified each creator. Beta: this endpoint is unlisted and its response shape may change without notice. # Search Source: https://docs.upriver.ai/api-reference/creators/search /api-reference/openapi.json post /v1/creators/search Unified creator search for exact, broad, and filter-only queries. **Exact lookup:** Provide `creator_url` (or an exact `query`) to quickly find the creator and linked channels. **Broad discovery:** Provide `query` with optional filters (platforms, category_ids, follower_bucket, follower range, country/language). **Filter-only browse:** Provide `category_ids` + `follower_bucket` without a text query to browse creators by category and size. Pass `next_cursor` from any search response back as `cursor` with the same query and filters to fetch the next page. Use the `include` query parameter for optional expansions. In `/creators/search`, include expansions are supported only for exact `creator_url` lookups. # Product Details Source: https://docs.upriver.ai/api-reference/products/product-details /api-reference/openapi.json post /v1/brand/product Provides details for a specific product including description, features, and pricing. Provide as much information as you have — more context improves accuracy. **Input:** - **product_name**: Required. - **product_url**, **brand_url**, **brand_name**: Optional. At least one required to identify the brand. **Effort Levels:** - **low**: fast extraction from the product page. - **high**: includes competitive research (alternatives). # Products List Source: https://docs.upriver.ai/api-reference/products/products-list /api-reference/openapi.json post /v1/brand/products Returns a list of products associated with a brand. Requires **brand_url** on every request, including pagination requests that send **cursor**. When **cursor** is provided, **brand_url** must match the brand encoded in that cursor. Response format: - **json**: Returns structured data with product list (default) - **text**: Returns natural language report The service prioritizes prominent and popular products from the brand's website. # Sponsor channels Source: https://docs.upriver.ai/api-reference/sponsorships/sponsor-channels /api-reference/openapi.json get /v1/sponsors/{sponsor_id}/channels List the social accounts publicly associated with a sponsor. # Sponsors Source: https://docs.upriver.ai/api-reference/sponsorships/sponsors /api-reference/openapi.json get /v1/sponsors Search for brands that recently sponsored media channels/publications. Provide exactly one scope filter: `categories` or `publication_url`. - `categories`: Find sponsors active in those content verticals. - `publication_url`: Find sponsors for a specific creator/publication. Use `platforms`, date range, and confidence parameters to refine results. # Sponsorships Source: https://docs.upriver.ai/api-reference/sponsorships/sponsorships /api-reference/openapi.json get /v1/sponsorships Return individual sponsored placements (content-level rows). Provide at least one of `sponsor_name`, `sponsor_id`, `sponsor_channel_id`, `brand_id`, `publication_url`, or `categories`. These can be combined, except `publication_url` and `categories` cannot be used together. # Media Categories Source: https://docs.upriver.ai/api-reference/taxonomy/media-categories /api-reference/openapi.json get /v1/media_categories Returns the media categories split into L1 (top-level) and L2 (second-level) lists. These categories can be used as a filter for sponsors, sponsorships. and other endpoints which support filtering by categories. # Media Categories Search Source: https://docs.upriver.ai/api-reference/taxonomy/media-categories-search /api-reference/openapi.json post /v1/categories/search Find the most relevant categories from the taxonomy for a given freeform text. Useful for discovering the best category for brand industries, target audiences, etc. Returns ordered matches with confidence scores. # Audio Playback Source: https://docs.upriver.ai/api-reference/trends/audio-playback /api-reference/openapi.json get /v2/trends/{trend_id}/playback Return a playback URL for a trend's audio media # Media Samples Source: https://docs.upriver.ai/api-reference/trends/media-samples /api-reference/openapi.json get /v2/trends/{trend_id}/media Returns video and audio url samples for a trend # Similar Trends Source: https://docs.upriver.ai/api-reference/trends/similar-trends /api-reference/openapi.json get /v2/trends/{trend_id}/similar Find trends similar to a given trend via embedding similarity # Traction Graph Source: https://docs.upriver.ai/api-reference/trends/traction-graph /api-reference/openapi.json get /v2/trends/{trend_id}/traction Pre-computed traction graph points for a trend. Returns both 'all' and 'recent' windows with estimated curves plus separate blended activity curves. # Trend Details Source: https://docs.upriver.ai/api-reference/trends/trend-details /api-reference/openapi.json get /v2/trends/{trend_id} Get a specific trend by its id. Use the /trends/{id}/playback endpoint to get a refreshed audio playback URL. # Trends List Source: https://docs.upriver.ai/api-reference/trends/trends-list /api-reference/openapi.json post /v2/trends/broad Get the latest trending formats. # Changelog Source: https://docs.upriver.ai/changelog Recent updates to the Upriver API # Changelog Stay up to date with the latest changes to the Upriver API. *** ## August 2026 ### Trends API: Multiple Content Structure Filters `/v2/trends/broad` now accepts a list for `content_structure`, such as `["structured", "loose"]`, and returns trends matching any requested value. Existing single-string requests continue to work. ### Trends API: Momentum Values Restored Trend list and detail responses now return the computed `momentum` value when posting-activity evidence is available, instead of leaving the field empty. ## July 2026 ### Trends API: Legacy `sort_by` Values Resolve to Current Sorts `/v2/trends/broad` accepts the legacy `sort_by` values `timeliness` and `momentum` and resolves them to their closest current equivalents: `newest` and `rising` respectively. The documented sort modes are `recommended`, `newest`, and `rising`; see the [Sorting & Ranking guide](/trends/sorting) for what each mode is for, the full legacy-value table, and how to build freshness badges from `freshness_score` and `timeliness_status`. ## June 2026 ### Creator API: MCP Tools for Creator Search and Discovery Two new MCP tools are now available at `mcp.upriver.ai`: `creator_search` finds creators by name, handle, content description, platform, category, or follower tier; `creator_get` returns a full creator profile by Upriver creator ID or channel URL, with optional enrichments (`bio`, `audience`, `brand_safety`). ### Sponsors API: `monetization_type`, `disclosure_tier`, and `is_first_party` Fields `/v1/sponsors` and `/v1/sponsorships` responses now include three new optional fields: `monetization_type` (`paid_partnership`, `affiliate`, `gifted`, `unknown`), `disclosure_tier` (confidence level of the disclosure signal), and `is_first_party`. Currently populated for Instagram sponsorships; YouTube placements return `null` for these fields. ### Breakout Topics: Entity `event` Filter `GET /v1/entities/breakout` now accepts an `event` query parameter to narrow results to entities breaking out in a specific competition — pass a freeform name like `"world cup"` or slug `world_cup` to filter entities linked to that event. Composes with existing `tag` and `temporal_status` filters. ### Breakout Topics: Entity List No Longer Includes Per-Topic Citations Per-topic `citations` and `citation_rate` fields on `GET /v1/entities/breakout` list responses are now empty — both load on demand from `GET /v1/entities/{entity_id}/breakout`. Callers relying on citations in the list response should switch to the detail endpoint. ### Categories API: Search No Longer Returns Invalid Category IDs Fixed `/v1/categories/search` returning category IDs outside the known taxonomy, which caused downstream errors when those IDs were passed to other endpoints. ### Breakout Topics: `temporal_status=upcoming` Returning HTTP 500 Fixed `temporal_status=upcoming` on `/v1/topics/breakout` and `/v1/entities/breakout` returning HTTP 500. ### Breakout Topics: Event `temporal_status` Field and Filter Topics linked to scheduled events now include a `temporal_status` field (`upcoming`, `ongoing`, `past`). Pass `temporal_status` as a filter on `/v1/topics/breakout` and `/v1/entities/breakout` to focus results on active or upcoming event-linked topics; the `breakout_list_topics` and `breakout_search_topics` MCP tools expose the same filter. ### Breakout Topics: Expanded Sort Options `/v1/topics/breakout` now accepts `sort_by=recommended` (default), `rising` (fastest-gaining), `top` (highest volume), and `newest` (most recently discovered); `importance` is accepted as an alias for `top`. The same vocabulary is available on `/v1/entities/breakout` with an additional `emerging` sort for forward-looking signals. ### Breakout Topics: `discovered_within_hours` Filter `/v1/topics/breakout` and `/v1/entities/breakout` now accept `discovered_within_hours` to limit results to topics or entities first seen within the last N hours — useful for surfacing only the freshest signals regardless of sort order. ### Trends API: `rising` Sort Alias `/v2/trends/broad` now accepts `sort_by=rising` as an alias for `momentum`, aligning sort vocabulary with the Breakout Topics API. ### Creator API: `limit` Parameter and Default Change `/v1/creators/search` now accepts a `limit` parameter (1–50). The default has changed from 20 to 10 — update any calls that relied on the previous default. ### Creator API: Natural-Language Content Search `/v1/creators/search` now accepts `content_query` for semantic discovery — describe what a creator makes (e.g. `"outdoor cooking tutorials"`) and the API returns the closest matching creators, ranked by content relevance. ### Breakout Topics: Entity Breakout API `GET /v1/entities/breakout` surfaces players, teams, and other named entities generating emerging coverage, with sort options including `recommended`, `recent`, `rising`, `emerging`, and `newest`. `GET /v1/entities/breakout/tags` returns active entity tag facets (sport, league, country) for filter discovery. `GET /v1/entities/{entity_id}/breakout` returns topics mentioning a specific entity. ### Creator API: `include=email` and `has_email` Filter Creator endpoints now support `include=email` to return a publicly available email address. Use `has_email=true` on `/v1/creators/search` to restrict results to creators with known contact emails. ### Products API: Garbled Product Descriptions Fixed product descriptions containing raw HTML character references (e.g., ` `, `(`) returned by certain e-commerce sites — affected descriptions now decode to readable text. ### Products API: Product Images and `include` Parameter `/v1/brand/products` now accepts an `include` parameter (`"description"`, `"image_url"`) to declare what each product entry should contain. Pass `include=["image_url"]` to receive a product image URL when one is available; omitting `include` returns descriptions only. Fields not requested are omitted from responses rather than returned as `null`. ### Creator API: Non-ASCII YouTube Handle Lookup Fixed creator lookups for YouTube handles that contain non-ASCII characters (e.g., accented letters like `é`) — handles were being silently truncated at the first non-ASCII character, causing lookups to fail or return the wrong creator. ### Breakout Topics: Citation Source Filter `/v1/topics/breakout` (list and search) now accepts `citation_sources` to restrict returned citations to specific source categories: `news`, `reddit`, and `twitter`. Useful for surfacing only journalistic sources or platform-specific discussion when the default mix isn't what you need. The filter is also available on the MCP `breakout_list_topics` and `breakout_search_topics` tools. ### Breakout Topics: MCP Server The Breakout Topics API is now accessible via the Model Context Protocol at `mcp.upriver.ai`, enabling AI agents (Claude, ChatGPT, Cursor, and others) to discover emerging topics natively. Available tools are `breakout_search_topics` and `breakout_list_topics`. ### Trends API: Momentum Sort Pagination Fixed pagination for `sort_by=momentum` — page 2 and beyond could return duplicate or permanently-skipped trends. Existing momentum pagination cursors are invalidated; restart pagination from the beginning to get consistent results. ### Sponsors API: Instagram Sponsorships Instagram sponsorship data is now available via `/v1/sponsors` and `/v1/sponsorships`. Native paid-partnership labels from Instagram posts are detected and resolved to brands, expanding coverage alongside existing YouTube and podcast sponsorships. ### Creator API: `name_or_handle` for Creator Search `/v1/creators/search` now accepts `name_or_handle` to resolve a creator by handle or display name — exact, prefix, and fuzzy substring matches are supported (e.g. `"beast"` finds `"MrBeast"`). The previous `query` and `creator_name` parameters are accepted as deprecated aliases for `name_or_handle` and will be removed in a future release. ### Creator API: Audience Country Filter `/v1/creators/search` now accepts `audience_country` (one or more ISO 3166-1 alpha-2 codes) to filter by where a creator's measured audience is located. `creator_country` also now accepts multiple codes in a single request for multi-country queries. ### Breakout Topics: Parameter Validation The breakout list endpoint now returns HTTP 400 for unknown `vertical` values (with a pointer to `GET /v1/topics/breakout/metadata`) and unknown `status` values instead of silently returning empty results or HTTP 500. `status=archived` has been removed — archived topics are never surfaced; use `emerging`, `active`, or `resolved`. The `include` parameter now validates against its allowed values (`citations`, `entities`). ### Creator API: Text Search Reliability Fixed `query` and `creator_name` searches on `POST /v1/creators/search` returning HTTP 500. URL-based lookups and filter-only browse were not affected. ### Creator API: Search Pagination Reliability Fixed pagination in `/v1/creators/search` so that browsing by category or follower tier reliably returns every page of results. *** ## May 2026 ### Creator API: Improved Country Matching and Coverage Filtering creator search by country (`creator_country`) is now more accurate and covers more creators. ### Trends API: New `newest` and `momentum` Sort Options `/v2/trends/broad` now accepts two more values for `sort_by`: `newest` orders trends by when they were first confirmed as real, and `momentum` surfaces trends with accelerating activity, comparing recent video volume to the prior period. ### Trends API: `emerged_at` Field `/v2/trends/broad` list and detail responses now include `emerged_at`, the timestamp when a trend first gathered enough activity to be considered emerging. This is the signal behind the `emerging` sort, so you can explain why one trend outranks another. ### Trends API: Commercial Music Approval Flag Trend list and detail responses now include `commercial_music_approved`, indicating whether a sound has been explicitly cleared for commercial and business use. This pairs with the existing `commercial_music_status=approved` filter. ### 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 an `associated_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 Fixed `include=relative_metrics` benchmarking a creator's channel against the wrong category cohort on warm cache hits. ### Sponsors API: Publication Category Labels Fixed `publication_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 for `bio`, `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 The `bio`, `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 support `include=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 The `UsageByFeature` 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 Fixed `relevance_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 stripping `published_at` and `duration_seconds` from `video_samples`. Both fields are now returned correctly. ### Breakout Topics: Citation Rate Topic detail responses now include a `citation_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 structured `min_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 via `include=audience`. Returns directional signals for age, gender, geography, languages, and interests. ### Creator API: Stable Creator IDs Creator endpoints now support `include=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 Added `include=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 safety `flags` 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 a `sound_duration` field. ### Agent Skill & llms.txt Upriver docs now include [`skill.md`](/ai/skillmd) and [`llms.txt`](/ai/llmstxt) for AI agents and coding assistants. These files provide structured API guidance, endpoint descriptions, and recommended workflows so your AI tools can integrate Upriver more effectively. ### 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 include `pct_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 Added `include=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 include `tags` 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 Added `include=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 Replaced `use_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 Renamed `canonical_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. Use `include=bio` to get a concise summary of the creator's background and content focus. ```bash theme={null} GET /v1/creators?url=https://youtube.com/@MrBeast&include=bio ``` *** ## 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_dimensions` endpoint * Faster response times for `/v1/trends/broad` endpoint * 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 Renamed `dynamic_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 Added `labels` 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 Added `include_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. ### Trends: Audio Playback Added `playback_url` for audio trend samples. *** ## 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. ### Sponsors API: Categories Filter sponsorships by media categories. ### 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. ### Audience Insights: Citations Added citation finding capability with source URLs. Enhanced creative guidance with citations. ### Audience Insights: Schema Improvements Simplified response schema with cleaner field naming. Updated personality and psychology field structures. # Introduction Source: https://docs.upriver.ai/index API for real-time context on creators, audiences, brands, trends, and sponsorships ## What is Upriver? [Upriver](https://upriver.ai/?ref=docs) provides an API that turns what's happening online into real-time, reliable context for AI applications. ## Core Features Upriver specializes in evidence-backed analysis on norms, influences, and aesthetics that come from online communities. * Brands: brands and how they're being discussed * Products: product mentions and use cases * Creators: relevant creators and profiles * Audiences: personas, interests, language, and humor * Trends: topics and formats gaining attention * Sponsorships: Brand-creator relationships and placements ## Popular Use Cases Developers blend Upriver's external data with internal data for uses cases like: Ground AI outputs in what people actually care about Power discovery and recommendations using relevance signals Identify relevant brands, creators, or audiences Surface our insights directly to end users ## For Agents + LLMs Building with agents or coding assistants? Give them the skill.md and they can use the API directly. Structured capabilities file for agents Documentation index for LLMs ## Get Started To get an API key, schedule an intro call: 20-minute intro call to discuss your use case and learn how Upriver can help. # MCP Server Source: https://docs.upriver.ai/mcp-server Connect any MCP-compatible AI assistant to Upriver — real-time intelligence on what's breaking out online and the creators behind it. Upriver's hosted **Model Context Protocol (MCP)** server brings real-time, evidence-backed context to any MCP-compatible assistant or agent. It's remote and hosted — there's nothing to install or run. Upriver tracks online culture in real time — both **what's** gaining traction and **who's** driving it. The server exposes two complementary slices: * **Breakout topics** — *what's* emerging: subjects gaining traction across tech, sports, and politics, each with grounded source citations so the model reasons from real evidence instead of guessing. * **Creators** — *who's* behind it: find creators by name, content, or audience filters, then pull a full profile to vet them. The two chain naturally — spot what's breaking out, then find the creators driving it (or start from a creator and see what's resonating). Upriver MCP access is provisioned per account. Connect any client below to sign in — if your account isn't enabled yet, you'll be pointed to [request access](https://dashboard.upriver.ai). ## Connect | | | | ------------- | ---------------------------------------------------------------------------- | | **Endpoint** | `https://mcp.upriver.ai/mcp` | | **Transport** | Streamable HTTP | | **Auth** | Sign in with Upriver (OAuth), or send your API key in the `X-API-Key` header | **OAuth sign-in works in every client.** The `X-API-Key` header is supported by Claude Code, Cursor, VS Code, Cline, Windsurf, Codex CLI, Goose, and Zed — but **not** by Claude's or ChatGPT's connector UIs, which are OAuth-only. ```bash theme={null} claude mcp add --transport http upriver https://mcp.upriver.ai/mcp ``` To use an API key instead of OAuth, pass it as a header: ```bash theme={null} claude mcp add --transport http upriver https://mcp.upriver.ai/mcp \ --header "X-API-Key: YOUR_UPRIVER_API_KEY" ``` Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project), then connect it in **Settings → Tools & Integrations** to sign in: ```json theme={null} { "mcpServers": { "upriver": { "url": "https://mcp.upriver.ai/mcp" } } } ``` For API-key auth, add `"headers": { "X-API-Key": "YOUR_UPRIVER_API_KEY" }`. VS Code uses a different shape — top-level **`servers`** and a required **`"type": "http"`**. Add to `.vscode/mcp.json` (or run **MCP: Add Server**): ```json theme={null} { "servers": { "upriver": { "type": "http", "url": "https://mcp.upriver.ai/mcp" } } } ``` For API-key auth, add `"headers": { "X-API-Key": "YOUR_UPRIVER_API_KEY" }`. In Claude, go to **Customize → Connectors → "+" → Add custom connector**, name it `Upriver`, paste `https://mcp.upriver.ai/mcp`, then **Connect** and sign in. Claude's connector is OAuth-only — there's no field for an API key. Don't add a raw `url` entry to `claude_desktop_config.json`; the desktop app rejects it. Use the **Remote Servers** tab (Transport: **Streamable HTTP**), or edit `cline_mcp_settings.json`. The `type` field is required, or Cline falls back to legacy SSE and fails: ```json theme={null} { "mcpServers": { "upriver": { "type": "streamableHttp", "url": "https://mcp.upriver.ai/mcp" } } } ``` Edit `~/.codeium/windsurf/mcp_config.json` — Windsurf's field is **`serverUrl`**: ```json theme={null} { "mcpServers": { "upriver": { "serverUrl": "https://mcp.upriver.ai/mcp" } } } ``` **Codex CLI (OpenAI)** ```bash theme={null} codex mcp add upriver --url https://mcp.upriver.ai/mcp --header X-API-Key=YOUR_UPRIVER_API_KEY ``` **ChatGPT** — Enable **Developer mode** (Settings → Apps & Connectors → Advanced), then **Settings → Connectors → Create**, name it `Upriver`, paste `https://mcp.upriver.ai/mcp`, choose **OAuth**, and sign in. (No custom-header field — OAuth only in the UI.) **Goose** — add to `~/.config/goose/config.yaml`: ```yaml theme={null} extensions: upriver: type: streamable_http uri: https://mcp.upriver.ai/mcp enabled: true headers: X-API-Key: "${UPRIVER_API_KEY}" ``` **Zed** — add to `settings.json` under `context_servers`: ```json theme={null} { "context_servers": { "upriver": { "url": "https://mcp.upriver.ai/mcp", "headers": { "X-API-Key": "YOUR_UPRIVER_API_KEY" } } } } ``` **JetBrains IDEs:** MCP works, but the IDE currently drops custom request headers and doesn't yet support OAuth for remote servers, so Upriver's `X-API-Key` auth can't connect there yet — we'll list it once JetBrains ships the fix. ## Tools available today Four read-only tools across the two slices. **Breakout topics** answer *what's* gaining traction; **creators** answer *who's* driving and relevant to it — so you can go from a trend to the people behind it, or start from a creator and see what's resonating. ### Breakout topics Subjects gaining traction across tech, sports, and politics. Each tool returns up to 25 topics per call (default 10), every topic carrying up to 5 source citations, with a `has_more` flag when more results exist beyond the page. **`breakout_search_topics`** — search breakout topics by keyword. | Parameter | Type | Description | | ------------------ | --------------------- | --------------------------------------------------------- | | `query` | string · **required** | Natural-language search, e.g. `"AI video effects"`. | | `vertical` | enum | Restrict to `tech`, `sports`, or `politics`. | | `limit` | integer | 1–25 (default 10). | | `citation_sources` | array | Restrict citations to any of `news`, `reddit`, `twitter`. | **`breakout_list_topics`** — browse breakout topics gaining traction right now. | Parameter | Type | Description | | ------------------ | ------- | ------------------------------------------------------------------------------------------------ | | `vertical` | enum | Restrict to `tech`, `sports`, or `politics`. | | `status` | enum | Lifecycle filter: `active` (default), `emerging`, `trending`, `declining`, `detected`, or `all`. | | `limit` | integer | 1–25 (default 10). | | `citation_sources` | array | Restrict citations to any of `news`, `reddit`, `twitter`. | Each topic includes its name, vertical, lifecycle status, a momentum signal, and its top citations (title, URL, source category, and publish time). ### Creators Find and vet creators across platforms — start with `creator_search` to find matches, then `creator_get` to pull one creator's full profile. **`creator_search`** — find creators by name/@handle, by what their content is about, or by filters. Returns lean matches (top channels + categories) plus `next_cursor` for paging. At least one of `name_or_handle`, `content_query`, or a filter is required. | Parameter | Type | Description | | -------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name_or_handle` | string | Find a creator by display name or @handle (exact, prefix, fuzzy). | | `content_query` | string | Describe the creator or content in plain language; results ranked by content match. | | `categories` | array | Free-text category keywords, e.g. `["gaming"]` or `["beauty", "skincare"]`. | | `platforms` | array | Restrict to platforms — `youtube`, `tiktok`, `instagram`, `x`, and others. | | `min_followers` / `max_followers` | integer | Approximate follower-count floor / ceiling based on recently observed counts. | | `follower_bucket` | array | Approximate audience-size bands (e.g. `100k_300k`). With `categories`, enables filter-only browse. Mutually exclusive with `min_followers`/`max_followers`. | | `creator_country` / `audience_country` | string | Where the creator / their audience is based (ISO 3166-1 alpha-2). | | `creator_language` | string | Creator's primary language, e.g. `en`. | | `has_email` | boolean | Only creators that have (or lack) a public email. | | `limit` | integer | 1–25 (default 10). | | `cursor` | string | Pass a previous response's `next_cursor` to page filter-only browse. | **`creator_get`** — get one creator's full profile by Upriver `creator_id` or channel URL. | Parameter | Type | Description | | --------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `creator` | string · **required** | An Upriver `creator_id` (UUID) or a full channel URL (e.g. `https://youtube.com/@handle`). A bare `@handle` isn't accepted — resolve it with `creator_search` first. | | `include` | array | Optional enrichments. Fast: `engagement_metrics`, `video_metrics`, `relative_metrics`, `email`. Slower (live research): `bio`, `audience`, `brand_safety`. Request only what you need. | Returns the profile (channels, categories, related creators) plus any requested enrichments. ## Access Upriver MCP access is provisioned per account. Request access at [dashboard.upriver.ai](https://dashboard.upriver.ai) or email [support@upriver.ai](mailto:support@upriver.ai). Once your account is enabled, the same Upriver sign-in (or API key) works across every MCP client — find your API key in the [Upriver dashboard](https://dashboard.upriver.ai). ## Troubleshooting | Symptom | Fix | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | "MCP access isn't enabled for this Upriver account yet" | Your account isn't provisioned yet — request access at [dashboard.upriver.ai](https://dashboard.upriver.ai). | | Prompted to sign in, or `401` | Complete the OAuth sign-in, or check that your `X-API-Key` header is set and valid. | | Tools don't appear after connecting | Reconnect and re-list tools. Make sure the transport is **Streamable HTTP**, not SSE. | | Claude or ChatGPT shows no API-key field | Those connector UIs are OAuth-only — use **Sign in with Upriver** instead. | | JetBrains IDE won't connect | Not supported yet (the IDE drops custom headers and lacks OAuth for remote servers). | ## More on the way Breakout topics and creators are the first of Upriver's capabilities to land as MCP tools. The rest of the API — audiences, brands, products, trends, and sponsorships — is documented in the [API reference](/), and we're rolling those out as MCP tools too. Request access and manage your account Give agents the full Upriver API reference # Sorting & Ranking Source: https://docs.upriver.ai/trends/sorting How the trend sort modes differ, what each one is for, and how the freshness and rising signals behave The [Trends List endpoint](/trends/overview-1) supports three sort modes via `sort_by`. Each answers a **different question**. Most confusion about trend ordering comes from expecting one mode to answer another mode's question. | `sort_by` | The question it answers | Use it for | | ------------------------- | ------------------------------------ | --------------------------------------- | | `recommended` *(default)* | "What's worth my attention overall?" | Browsing; a balanced view of what's hot | | `newest` | "What's new since I last checked?" | Daily/weekly catch-up on new arrivals | | `rising` | "What's inflecting **right now**?" | Timing: catching a wave before it peaks | ## Biggest is not the same as rising `rising` ranks by **acceleration of posting activity**: is this trend's content being created faster than its own recent baseline? It does not rank by total size. A trend with millions of views and a large, steady stream of videos is *established*: it tops `recommended`, but its curve is flat, so it sits low on `rising`. A small trend whose activity is compounding week over week is the one `rising` is built to surface. That's the window where creating content for it puts you early. Two trend activity charts: a large steady trend that ranks first on Recommended but reads Steady on Rising, next to a small accelerating trend that reads Rising

Two trend activity charts: a large steady trend that ranks first on Recommended but reads Steady on Rising, next to a small accelerating trend that reads Rising

If a 6.1M-view trend appears below a 43K-view trend on `rising`, that is the sort working as intended: the smaller trend is accelerating harder *relative to its own baseline*. For "biggest overall", use `recommended`. ## Rising means rising *now* The rising signal is anchored to a trend's **latest evidence** and fades as that evidence ages. Two trends with the same climb rank very differently if one climbed this week and the other went quiet three weeks ago: Two identical climbing curves; the one whose latest video is 2 days old reads Rising +0.29 while the one quiet for 3 weeks reads roughly zero

Two identical climbing curves; the one whose latest video is 2 days old reads Rising +0.29 while the one quiet for 3 weeks reads roughly zero

Each trend's `momentum` value ranges from **−1 to +1**: positive = building, negative = fading, near zero = steady, too little evidence to judge, or evidence that has aged out of relevance. There is no cliff: the value decays smoothly, so a trend that was hot three weeks ago drifts down the list rather than vanishing. ## Freshness follows the most recent wave `freshness_score` (0–1) measures **how recent a trend's content activity is**, weighted toward its newest wave of videos. It is a *recency level*, independent of size. A trend can be small and fresh, or huge and stale. Trends often resurface: a format that had early buzz and then a strong second wave reads as fresh again, because the score follows the recent wave rather than averaging over the trend's whole lifetime. A trend with early buzz plus a new second wave scoring 0.62 active, next to a trend with early buzz only scoring 0.18 stale

A trend with early buzz plus a new second wave scoring 0.62 active, next to a trend with early buzz only scoring 0.18 stale

`timeliness_status` bands the same signal into `recent` / `active` / `stale` / `cold` if you prefer labels over thresholds. If you're rendering your own "fresh" or "hot" badge, decide which question it should answer. **"Recently active content"** → threshold on `freshness_score` (or use `timeliness_status`). **"Act on this now"** → threshold on `momentum` (e.g. ≥ 0.1). **"New to the catalog"** → sort by `newest` and compare `emerged_at` against your last visit. Mixing these produces badges that feel wrong on big-but-established trends. ## Field quick reference | Field | Meaning | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `freshness_score` | 0–1 recency of content activity, weighted toward the newest wave. Size-blind. | | `timeliness_status` | The same signal as labels: `recent`, `active`, `stale`, `cold`. | | `momentum` | −1..+1 trajectory of posting activity, decaying as the latest evidence ages. | | `emerged_at` | When the trend first accumulated enough confirmed videos to count as a real trend in our catalog. This is when *we confirmed it*; for formats where we backfill older example videos, it can be later than the oldest video you see on the trend. | ## Which sort for which workflow * **"I check in every morning"**: use `newest`, and stop at the first trend you recognize from yesterday. * **"I plan content weekly"**: use `recommended`, filtered to your categories. * **"I want to catch waves early"**: use `rising`, and prioritize entries that are also `recent`/`active` on `timeliness_status`. ## Legacy sort values Older `sort_by` values keep working forever; they resolve to their closest current equivalent instead of erroring: | Value sent | Resolves to | Notes | | ------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `momentum` | `rising` | Renamed; identical behavior. | | `timeliness` | `newest` | Retired as a distinct sort in July 2026. For a freshness-ordered view, use `newest` with the `timeliness_status=recent` filter, or order client-side by `freshness_score`. | | `emerging` | (unchanged) | Still accepted as its own ordering, by `emerged_at`. For most catch-up workflows `newest` is the better fit. |