# Upriver API Docs

## Docs

- [Introduction](https://docs.upriver.ai/index): Structured social context for AI applications
- [Quickstart](https://docs.upriver.ai/quickstart): Get started with the Upriver API
- [Changelog](https://docs.upriver.ai/changelog): Recent updates to the Upriver API
- [Brand Details](https://docs.upriver.ai/api-reference/brands/brand-details): Get brand identity, positioning, and brand language. Preferred input: brand_url (brand website URL). Use the auto field only if you have freeform text instead of a URL. Response is required before calling /v2/audience_insights.
- [Product Details](https://docs.upriver.ai/api-reference/products/product-details): Get details for a specific product including description, features, and pricing. Requires brand_name and product_name — use the exact name and url values from the /v1/brand/products response (e.g., if products returns { "name": "Air Max 270", "url": "https://nike.com/air-max-270" }, pass product_name="Air Max 270" and product_url="https://nike.com/air-max-270"). Always include product_url when available for reliable results.
- [Products](https://docs.upriver.ai/api-reference/products/products): Get a paginated list of products for a brand. Preferred input: brand_url. Returns a best-effort exhaustive list. Use cursor from response to paginate for more results.
- [Creator Details](https://docs.upriver.ai/api-reference/creators/creator-details): Get creator profile info including channels, labels, engagement metrics, and bio. Requires url (social media profile URL). Always include engagement_metrics and bio via the include parameter for best results. The include parameter is a repeated query param — e.g. include=engagement_metrics&include=bio. Available values: engagement_metrics, video_metrics, bio.
- [Batch Creator Details](https://docs.upriver.ai/api-reference/creators/batch-creator-details): 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.
- [Get Creator by ID](https://docs.upriver.ai/api-reference/creators/get-creator-by-id): Get a creator's profile using their stable Upriver creator ID. If the ID has been merged into another creator, the response includes redirect information and the X-Creator-Redirect header.
- [Dimensions](https://docs.upriver.ai/api-reference/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 /v2/audience_insights unless granular dimension-level data is specifically needed. Rate limited to 1 request per minute.
- [Personas](https://docs.upriver.ai/api-reference/audience/personas): Get 3-5 detailed audience personas with psychographics, behaviors, motivators, and barriers. Requires brief — construct from user context (e.g., 'Describe the audience for Nike running shoes'). Works best when you pass the full JSON response from /v1/brand/research as the brand field, and the products array from /v1/brand/products as the products field (the schema accepts the same shape those endpoints return). Set response_config.citations_mode to 'async' for faster responses, then use meta.continuation_token from the response to retrieve evidence via the citations endpoint.
- [Personas - Citations](https://docs.upriver.ai/api-reference/audience/personas-citations): Retrieve behavioral evidence and citations for audience personas. Call after /v2/audience_insights with response_config.citations_mode='async', using the meta.continuation_token value from the personas response.
- [Sponsors](https://docs.upriver.ai/api-reference/sponsorships/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. Returns matching brands with an example of their latest sponsorship placement.
- [Sponsorships](https://docs.upriver.ai/api-reference/sponsorships/sponsorships): Return individual sponsored placements (content-level rows). Filter by brand (name or ID), content category, or publication_url (a specific creator's YouTube channel, Substack, etc.) to find specific placements. Each result is a single sponsorship instance with placement details.
- [Overview](https://docs.upriver.ai/api-reference/trends/overview): 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 trend_type (sound, challenge, template, theme), 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.
- [Trend Details](https://docs.upriver.ai/api-reference/trends/trend-details): Get full details for a specific trend by ID, including description, metrics, and metadata. Use after discovering trends via /v2/trends/broad.
- [Media Samples](https://docs.upriver.ai/api-reference/trends/media-samples): 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.
- [Audio Playback](https://docs.upriver.ai/api-reference/trends/audio-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.
- [Search](https://docs.upriver.ai/api-reference/trends/search): Fallback search for TikTok trends by brand or category context. Trends are TikTok-sourced but applicable across short-form video platforms. In most cases, prefer /v2/trends/broad for better coverage and quality. Use this only when you need to search by a specific brand_url or narrow keyword that /v2/trends/broad doesn't support. Results may be less comprehensive.
- [List Breakout Topics](https://docs.upriver.ai/api-reference/breakout-topics/list-breakout-topics): List emerging topics gaining traction in online communities. Filter by vertical — only valid values are: tech, sports, politics. Also filter by category and status (e.g., status=emerging for newly rising topics). Returns topics ranked by importance with engagement signals.
- [List Meta-Topics](https://docs.upriver.ai/api-reference/breakout-topics/list-meta-topics): List persistent narrative groups (meta-topics) that track long-running stories across days or weeks. Ranked by composite score combining evidence depth, peak intensity, and recency.
- [Get Meta-Topic Detail](https://docs.upriver.ai/api-reference/breakout-topics/get-meta-topic-detail): Get detailed view of a meta-topic including its member topics and direct citations.
- [Get Breakout Topics Metadata](https://docs.upriver.ai/api-reference/breakout-topics/get-breakout-topics-metadata): Get available categories within each vertical for filtering breakout topics. Valid verticals are: tech, sports, politics. Use this to discover category values within a vertical.
- [Search Breakout Topics](https://docs.upriver.ai/api-reference/breakout-topics/search-breakout-topics): 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.
- [Find Similar Topics](https://docs.upriver.ai/api-reference/breakout-topics/find-similar-topics): 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.
- [Get Breakout Topic](https://docs.upriver.ai/api-reference/breakout-topics/get-breakout-topic): Get full details for a single breakout topic by ID, including description, importance score, status, and citations.
- [Media Categories Search](https://docs.upriver.ai/api-reference/taxonomy/media-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.
- [Media Categories](https://docs.upriver.ai/api-reference/taxonomy/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.

## Optional

- [Upriver Website](https://upriver.ai)