---
name: upriver
description: "API for real-time context on creators, audiences, brands, trends, and sponsorships."
metadata:
    mintlify-proj: upriver
    version: "1.0.0"
---

## Capabilities

Upriver gives AI agents structured consumer context via a REST API. Use it to:
understand brands, products, and their audiences,
find creators and sponsorship relationships,
and track trending formats and emerging topics.
All responses are JSON with cursor-based pagination on list endpoints.

## Skills

### Brands

- **Brand Research** (`POST /v1/brand/research`): Get brand identity, positioning, and brand language. Preferred input: brand_url (brand website URL). Response is required before calling /v2/audience_insights. Returns brand_name, positioning, brand_language, competitors, and metadata.
  - Parameters: Body — `brand_url`

### Products

- **Product Details** (`POST /v1/brand/product`): Get details for a specific product. Requires product_name and at least one of product_url, brand_url, or brand_name. Provide as much as you have — more context improves results. Use values from the /v1/brand/products response when chaining. Returns product description, features, pricing, and URLs.
  - Parameters: Body — `product_name`*, `product_url`, `brand_url`, `brand_name`
- **Products List** (`POST /v1/brand/products`): Get a paginated list of products for a brand. Provide brand_url on every request, including when paging with cursor. Returns a best-effort exhaustive list. Use cursor from the response to request the next page. Returns a products array with name, description, and URL per product, plus a cursor for pagination.
  - Parameters: Body — `brand_url`*, `cursor`

### Creators

- **Creator Profile by URL** (`GET /v1/creators`): Lookup a creator profile by social media profile URL. Returns the same payload shape as /v1/creators/`{creator_id}`; only the lookup key differs. Use `include` for optional enrichments (`engagement_metrics`, `video_metrics`, `relative_metrics`, `bio`, `audience`, `brand_safety`); see Creator Engagement Metrics (/metrics) for guide-level details. Returns profile info, channel URLs, labels, and include-driven enrichments such as engagement_metrics, video_metrics, audience, and bio.
  - Parameters: `url`*, `include`
- **Batch Creator Details** (`POST /v1/creators/batch`): Look up 1-10 creators at once by social media profile URL. Body takes a urls array of profile URLs (e.g., urls: ['https://...', ...]). Useful when checking multiple creators from sponsorship results or batch processing. Note: engagement metrics are not available in batch responses. Returns a creators array with profile info per URL.
  - Parameters: Body — `urls`*
- **Creator Profile by ID** (`GET /v1/creators/{creator_id}`): Lookup a creator profile by stable Upriver creator ID. Returns the same payload shape as /v1/creators; only the lookup key differs. Merged IDs return redirect metadata in the response body/header. Use `include` for optional enrichments (`engagement_metrics`, `video_metrics`, `relative_metrics`, `bio`, `audience`, `brand_safety`); see Creator Engagement Metrics (/metrics) for guide-level details.
  - Parameters: `creator_id`*, `include`

### Audience

- **Dimensions** (`POST /v1/audience_dimensions`): Extract atomic behavioral, motivational, and lifestyle dimensions for a brand's audience. Input: brand_url. Returns granular longtail audience facts useful for programmatic matching. Slower than Personas due to extensive research. In most cases, prefer /v3/audience_insights unless granular dimension-level data is specifically needed. Rate limited to 1 request per minute. Returns an array of behavioral, motivational, and lifestyle dimension objects.
  - Parameters: Body — `brand_url`*
- **Personas (v3)** (`POST /v3/audience_insights`): Get detailed audience personas for a brand, grounded in real online conversations. Pass brand_url directly — no prior brand/research call needed. Returns personas with purchase triggers, barriers, behaviors, language patterns, and real-world citations.
  - Parameters: Body — `brand_url`*, `query`, `include_citations`

### Sponsorships

- **Sponsors** (`GET /v1/sponsors`): Search for brands that have recently sponsored content in media channels or publications. Filter by content category (e.g., gaming, tech) to find sponsors within a vertical, or by publication_url to find sponsors of a specific creator's channel or newsletter. Provide exactly one scope filter: categories or publication_url. Returns matching brands with an example of their latest sponsorship placement.
  - Parameters: `categories`, `publication_url`, `limit`, `cursor`
- **Sponsorships** (`GET /v1/sponsorships`): Return individual sponsored placements (content-level rows). Provide at least one of: sponsor_name, brand_id, publication_url, or categories. These can be combined, except publication_url and categories cannot be used together. Each placement includes brand, publication, content URL, and dates.
  - Parameters: `brand_id`, `sponsor_name`, `publication_url`, `categories`, `limit`, `cursor`

### Trends

- **Trends List** (`POST /v2/trends/broad`): Get the latest trending TikTok video formats and templates — the primary endpoint for trend discovery. Trends are sourced from TikTok but are useful for ideation across platforms (Instagram Reels, YouTube Shorts, etc.). Filter by uses_specific_sound, participation_type, content_structure, has_text_template, include/exclude tags (e.g., exclude_tags=['nsfw']), and duration range. Each trend in the response has an id field — use it as the trend_id path parameter for the trend details, media, and playback endpoints. Returns a trends array; each trend includes id, title, description, trend_type, tags, and metric summaries.
  - Parameters: Body — `uses_specific_sound`, `participation_type`, `content_structure`, `sort_by`, `has_text_template`, `tags`, `exclude_tags`, `min_duration`, `max_duration`, `cursor`
- **Trend Details** (`GET /v2/trends/{trend_id}`): Get full details for a specific trend by ID, including description, metrics, and metadata. Use after discovering trends via /v2/trends/broad. Includes example URLs and full metric breakdowns.
  - Parameters: `trend_id`*
- **Media Samples** (`GET /v2/trends/{trend_id}/media`): Get video samples for a trend — returns URLs to example TikTok videos demonstrating the trend. Filter by kind (video, audio) and limit the number of samples. Returns a media array of video/audio sample URLs.
  - Parameters: `trend_id`*, `kind`, `limit`
- **Audio Playback** (`GET /v2/trends/{trend_id}/playback`): Get the top associated audio playback URL for a trend's sound. Use when the user wants the audio/music behind a trend rather than full video samples.
  - Parameters: `trend_id`*, `media_key`
- **Similar Trends** (`GET /v2/trends/{trend_id}/similar`): Find trends similar to a given trend. Use a trend_id from /v2/trends/broad results. Returns up to limit (default 5, max 20) related trends ranked by similarity.
  - Parameters: `trend_id`*, `limit`
- **Traction Graph** (`GET /v2/trends/{trend_id}/traction`): Get the traction graph for a trend — returns pre-computed estimated traction curves, plus the underlying blended activity curves, for both the full time range and a focused recent window.
  - Parameters: `trend_id`*, `metadata_mode`

### Breakout Topics

- **List Breakout Topics** (`GET /v1/topics/breakout`): List emerging topics gaining traction in online communities. Filter by vertical — only valid values are: tech, sports, politics. Category filtering is currently only supported for sports in topic mode. Also filter by status (e.g., status=emerging for newly rising topics). Use surface_mode=story to return deduped derived story surfaces instead of raw topics.
  - Parameters: `vertical`, `category`, `status`, `limit`, `cursor`, `surface_mode`, `include`, `include_citations`
- **Get Breakout Topics Metadata** (`GET /v1/topics/breakout/metadata`): Get available breakout topic filters. Valid verticals are: tech, sports, politics. Category filters are currently only supported for the sports vertical. Returns available categories grouped by vertical.
- **List Narratives** (`GET /v1/topics/breakout/narratives`): List narrative arcs that group related breakout topics. Ordered by most recently updated.
  - Parameters: `vertical`, `limit`, `offset`
- **Get Narrative** (`GET /v1/topics/breakout/narratives/{narrative_id}`): Get a narrative arc with its member breakout topics.
  - Parameters: `narrative_id`*
- **Search Breakout Topics** (`POST /v1/topics/breakout/search`): Search for specific breakout topics by keyword within a vertical. Use when looking for topics about a particular subject (e.g., search 'AI' within the tech vertical). Uses hybrid search for relevance. Returns ranked topic matches with relevance scores.
  - Parameters: Body — `query`*, `vertical`, `mode`, `surface_mode`, `limit`, `include`, `include_citations`, `query_context`, `kalshi_event_url`
- **Find Similar Topics** (`POST /v1/topics/breakout/similar`): Find topics similar to a given topic by semantic similarity. Use when a user finds an interesting topic and wants to discover adjacent or related emerging topics. Returns topics semantically similar to the input topic.
  - Parameters: Body — `topic_id`*, `limit`, `include`, `include_citations`
- **Get Breakout Topic** (`GET /v1/topics/breakout/{topic_id}`): Get full details for a single breakout topic by ID, including description, importance score, status, and citations.
  - Parameters: `topic_id`*
- **Get Topic Cluster View** (`GET /v1/topics/breakout/{topic_id}/cluster`): Get a derived cluster view around a breakout topic. This groups semantically related topics without implying linear order.
  - Parameters: `topic_id`*, `include`
- **Get Topic Story View** (`GET /v1/topics/breakout/{topic_id}/story`): Get the best available derived story surface around a breakout topic. Prefers a strict timeline when available, otherwise falls back to a related topical cluster or the topic itself.
  - Parameters: `topic_id`*, `include`
- **Get Topic Timeline View** (`GET /v1/topics/breakout/{topic_id}/timeline`): Get a derived timeline view around a breakout topic. This only returns multi-topic timeline surfaces when the graph supports a coherent progression.
  - Parameters: `topic_id`*, `include`

### Taxonomy

- **Media Categories Search** (`POST /v1/categories/search`): Find the most relevant categories from the taxonomy for a given freeform text (e.g., `{ "text": "gaming and esports" }`). Useful for discovering valid category values to pass as filters to the sponsors, sponsorships, and breakout topics endpoints. Returns ordered category matches with confidence scores.
  - Parameters: Body — `text`*
- **Media Categories** (`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.

## Workflows

### Find Trending Content Opportunities
1. `POST /v2/trends/broad` — browse latest TikTok trends (filter by trend_type, tags, duration)
2. `GET /v2/trends/{trend_id}` — get full trend details and metadata
3. `GET /v2/trends/{trend_id}/media` — get video samples demonstrating the trend
4. `GET /v2/trends/{trend_id}/playback` — get the trend's audio playback URL
5. `GET /v1/topics/breakout` — identify emerging breakout topics across verticals

### Build Audience Understanding
1. `POST /v3/audience_insights` — generate grounded personas with real-world citations (pass brand_url directly)
2. `POST /v1/audience_dimensions` — extract granular behavioral and lifestyle dimensions
3. `POST /v1/categories/search` — classify audience interests via taxonomy

### Analyze Sponsorship Landscape
1. `GET /v1/sponsors` — discover brands sponsoring content (filter by categories, publication_url, platforms)
2. `GET /v1/sponsorships` — get individual sponsored placements (filter by brand_name, publication_url, categories)
3. `GET /v1/creators` — get creator profiles for publications in sponsorship results
4. `POST /v1/creators/batch` — batch lookup multiple creators from sponsorship results

## Integration

- **Base URL:** `https://api.upriver.ai`
- **Authentication:** `X-API-Key` header
- **Format:** JSON request/response
- **Pagination:** Cursor-based (`cursor` parameter) on list endpoints
- **Rate limits:** Per-key; see response headers. Note: `/v1/audience_dimensions` is limited to 1 request per minute.
- **Errors:** Error responses return a JSON body with a `detail` field describing the issue. Common codes: `400` (invalid input), `401` (missing or invalid API key), `403` (insufficient permissions), `429` (rate limit exceeded — retry after backoff), `500` (server error — retry with exponential backoff).
- **Effort levels:** Most endpoints support an `effort` parameter. Default (`auto`) is recommended. Use `low` when speed is critical and less detail is acceptable.

## Context

- [API Reference](https://docs.upriver.ai/api-reference)
- [Changelog](https://docs.upriver.ai/changelog)
- [OpenAPI Spec](https://docs.upriver.ai/api-reference/openapi.json)
- [llms.txt](https://docs.upriver.ai/llms.txt)