Skip to main content
GET
/
v1
/
sponsors
cURL
curl -X GET 'https://api.upriver.ai/v1/sponsors?industry=tech' \
  -H 'X-API-Key: YOUR_API_KEY'
{
  "results": [
    {
      "partner_name": "Microsoft",
      "most_recent_ad": {
        "publication_name": "TechCrunch",
        "publication_url": "https://techcrunch.com",
        "publication_categories": [
          "technology",
          "startups"
        ],
        "publication_platform": "substack",
        "content_url": "https://example.com/article",
        "sponsor_type": "explicit_ad",
        "published_date": "2024-03-15",
        "evidence": {
          "source": "transcript",
          "excerpt": "...thanks to Acme for sponsoring today's video--use code GADGET for 10%...",
          "offset_seconds": 92.5,
          "confidence": 0.88
        }
      },
      "sponsor_domain": "microsoft.com",
      "sponsor_linkedin_url": "https://www.linkedin.com/company/microsoft",
      "sponsor_description": "<string>",
      "match_type": "exact",
      "similarity_score": 123,
      "total_ads_found": 5
    }
  ],
  "total_count": 123,
  "industry_category": "<string>",
  "next_cursor": "<string>",
  "has_more": false
}

Authorizations

​
X-API-Key
string
header
required

Query Parameters

​
categories
string[] | null

Content-vertical phrases or keywords (e.g. 'consumer tech', 'startup tools', 'personal finance'). Not brand or company names. Free-form strings are normalized to our standard category taxonomy and used to scope the search.

​
publication_url
string | null

A creator's publication URL (YouTube channel, Substack newsletter, podcast, etc.) to find its sponsors.

​
platforms
string[] | null

Platforms to include when searching for sponsors. If omitted, results include all available platforms.

​
confidence_threshold
number
default:0.5

Minimum sponsorship confidence threshold

Required range: 0 <= x <= 1
​
limit
integer
default:20

Maximum number of results per page. Requesting more than 20 results requires a credits-based plan.

Required range: 1 <= x <= 50
​
cursor
string | null

Pagination cursor from previous response's next_cursor field

​
include_evidence
boolean
default:false

Include structured evidence for the most recent ad (source, excerpt, and transcript offset when available)

​
sponsor_types
string[] | null

Filter by sponsorship types. When omitted, defaults to ['explicit_ad', 'promotion', 'unknown']. Other valid values include: 'implicit_ad', 'affiliate', 'merch_store', 'self_promotion'.

​
sponsor_type
string[] | null

Alias for sponsor_types; accepts a single value or repeated values.

​
top_k_categories
integer
default:3

When using 'categories', number of category matches to consider per query

Required range: 1 <= x <= 10
​
days_back
integer
default:90

Time window in days (default 90). Ignored when since is provided.

Required range: 1 <= x <= 365
​
since
string | null

Start date (YYYY-MM-DD, inclusive). Overrides days_back. Required when until is provided.

​
until
string | null

End date (YYYY-MM-DD, inclusive). Defaults to today when only since is provided.

​
sort_by
enum<string>
default:total_ads

Sort order for results. 'total_ads' (default) ranks brands by number of placements. 'recent' ranks by most recent ad date.

Available options:
total_ads,
recent
​
similar_to
string | null

Temporarily unavailable. Reserved for finding sponsors for brands similar to this apex domain, excluding the specified brand. Cannot be combined with categories or publication_url.

Response

Successful Response

Response for simplified partner search by industry

​
results
SimplifiedPartnerSearchResult · object[]
required

List of partner content results

​
total_count
integer
required

Total number of results found

​
industry_category
string | null

The industry category searched

​
next_cursor
string | null

Cursor for fetching the next page of results

​
has_more
boolean
default:false

Whether there are more results available