> ## Documentation Index > Fetch the complete documentation index at: https://docs.upriver.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/sponsors openapi: 3.1.0 info: title: Upriver API description: >- A social insights API for ad generation platforms. It provides structured signals, like psychographics, behavioral insights, trends, and audience language, to help AI models generate relevant, higher-converting ads. version: 1.0.0 servers: - url: https://api.upriver.ai description: Production API server security: [] tags: - name: Brands - name: Products - name: Creators - name: Audience - name: Sponsorships - name: Trends - name: Breakout Topics - name: Taxonomy paths: /v1/sponsors: get: tags: - Sponsorships summary: Sponsors description: >- 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. operationId: sponsors parameters: - name: categories in: query required: false schema: anyOf: - type: array items: type: string maxItems: 3 - type: 'null' description: >- 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. Mutually exclusive with publication_url. examples: - - consumer tech - startup tools title: Categories description: >- 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. Mutually exclusive with publication_url. example: - consumer tech - startup tools - name: publication_url in: query required: false schema: anyOf: - type: string - type: 'null' description: >- A creator's publication URL (YouTube channel, Substack newsletter, podcast, etc.) to find its sponsors. Mutually exclusive with categories. examples: - https://techweekly.substack.com title: Publication Url description: >- A creator's publication URL (YouTube channel, Substack newsletter, podcast, etc.) to find its sponsors. Mutually exclusive with categories. - name: platforms in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Platforms to include when searching for sponsors. If omitted, results include all available platforms. examples: - - substack - podcast title: Platforms description: >- Platforms to include when searching for sponsors. If omitted, results include all available platforms. - name: confidence_threshold in: query required: false schema: type: number maximum: 1 minimum: 0 description: Minimum sponsorship confidence threshold default: 0.5 title: Confidence Threshold description: Minimum sponsorship confidence threshold - name: limit in: query required: false schema: type: integer maximum: 50 minimum: 1 description: >- Maximum number of results per page. Requesting more than 20 results requires a credits-based plan. default: 20 title: Limit description: >- Maximum number of results per page. Requesting more than 20 results requires a credits-based plan. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: Pagination cursor from previous response's next_cursor field title: Cursor description: Pagination cursor from previous response's next_cursor field - name: include_evidence in: query required: false schema: type: boolean description: >- Include structured evidence for the most recent ad (source, excerpt, and transcript offset when available) default: false title: Include Evidence description: >- Include structured evidence for the most recent ad (source, excerpt, and transcript offset when available) - name: sponsor_types in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Filter by sponsorship types. When omitted, defaults to ['explicit_ad', 'implicit_ad', 'affiliate', 'promotion', 'unknown']. Other valid values include: 'merch_store', 'self_promotion'. examples: - - explicit_ad - implicit_ad - affiliate - promotion - unknown title: Sponsor Types description: >- Filter by sponsorship types. When omitted, defaults to ['explicit_ad', 'implicit_ad', 'affiliate', 'promotion', 'unknown']. Other valid values include: 'merch_store', 'self_promotion'. - name: sponsor_type in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Alias for sponsor_types; accepts a single value or repeated values. title: Sponsor Type description: Alias for sponsor_types; accepts a single value or repeated values. - name: days_back in: query required: false schema: type: integer maximum: 365 minimum: 1 description: Time window in days (default 90). Ignored when since is provided. default: 90 title: Days Back description: Time window in days (default 90). Ignored when since is provided. - name: since in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Start date (YYYY-MM-DD, inclusive). Overrides days_back. Required when until is provided. title: Since description: >- Start date (YYYY-MM-DD, inclusive). Overrides days_back. Required when until is provided. - name: until in: query required: false schema: anyOf: - type: string - type: 'null' description: >- End date (YYYY-MM-DD, inclusive). Defaults to today when only since is provided. title: Until description: >- End date (YYYY-MM-DD, inclusive). Defaults to today when only since is provided. - name: sort_by in: query required: false schema: enum: - total_ads - recent type: string description: >- Sort order for results. 'total_ads' (default) ranks brands by number of placements. 'recent' ranks by most recent ad date. default: total_ads title: Sort By description: >- Sort order for results. 'total_ads' (default) ranks brands by number of placements. 'recent' ranks by most recent ad date. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SimplifiedPartnerSearchResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] x-code-samples: - lang: curl source: |- curl -X GET 'https://api.upriver.ai/v1/sponsors?industry=tech' \ -H 'X-API-Key: YOUR_API_KEY' components: schemas: SimplifiedPartnerSearchResponse: properties: results: items: $ref: '#/components/schemas/SimplifiedPartnerSearchResult' type: array title: Results description: List of partner content results total_count: type: integer title: Total Count description: Number of results in the current page (not a grand total) industry_category: anyOf: - type: string - type: 'null' title: Industry Category description: The industry category searched next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: Cursor for fetching the next page of results has_more: type: boolean title: Has More description: Whether there are more results available default: false type: object required: - results - total_count title: SimplifiedPartnerSearchResponse description: Response for simplified partner search by industry HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError SimplifiedPartnerSearchResult: properties: partner_name: type: string title: Partner Name description: Name of the partner/sponsor entity example: Microsoft sponsor_domain: anyOf: - type: string - type: 'null' title: Sponsor Domain description: Canonical apex domain associated with the sponsor when available example: microsoft.com sponsor_linkedin_url: anyOf: - type: string - type: 'null' title: Sponsor Linkedin Url description: LinkedIn company profile URL for the sponsor when available example: https://www.linkedin.com/company/microsoft sponsor_description: anyOf: - type: string - type: 'null' title: Sponsor Description description: Brief description of the sponsor brand when available total_ads_found: type: integer title: Total Ads Found description: >- Total number of sponsored content pieces found across all publications default: 1 example: 5 most_recent_ad: $ref: '#/components/schemas/MostRecentAd' type: object required: - partner_name - most_recent_ad title: SimplifiedPartnerSearchResult description: Partner search result showing aggregated sponsorship data ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError MostRecentAd: properties: publication_name: type: string title: Publication Name description: Name of the publication where the ad appeared example: TechCrunch publication_url: anyOf: - type: string - type: 'null' title: Publication Url description: URL of the publication example: https://techcrunch.com publication_categories: items: type: string type: array title: Publication Categories description: Categories of the publication example: - technology - startups publication_platform: anyOf: - type: string - type: 'null' title: Publication Platform description: Platform of the publication example: substack content_url: anyOf: - type: string - type: 'null' title: Content Url description: URL of the specific content containing the ad, if available example: https://example.com/article sponsor_type: anyOf: - type: string - type: 'null' title: Sponsor Type description: >- Type of sponsorship detected for the most recent ad (e.g., explicit_ad, promotion, affiliate, unknown). example: explicit_ad published_date: anyOf: - type: string - type: 'null' title: Published Date description: Date when this ad was published (YYYY-MM-DD) example: '2024-03-15' evidence: anyOf: - $ref: '#/components/schemas/AdEvidence' - type: 'null' description: >- Structured evidence for the most recent ad, including source and offsets. Returned only when 'include_evidence=true'. type: object required: - publication_name title: MostRecentAd description: Details from the partner's most recent advertisement AdEvidence: properties: source: anyOf: - type: string - type: 'null' title: Source description: >- Origin of the evidence (e.g., 'transcript', 'description', 'post_body', 'title'). example: transcript excerpt: anyOf: - type: string - type: 'null' title: Excerpt description: >- Short excerpt around the sponsor mention. May be raw text or HTML depending on source. example: >- ...thanks to Acme for sponsoring today's video--use code GADGET for 10%... offset_seconds: anyOf: - type: number - type: 'null' title: Offset Seconds description: >- Approximate timestamp in seconds when source is 'transcript'. Null for sources without timing (e.g., description). example: 92.5 confidence: anyOf: - type: number - type: 'null' title: Confidence description: >- Detection confidence for this specific piece of evidence (0-1), when available. example: 0.88 type: object title: AdEvidence description: Structured evidence about where/how the sponsor was detected. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ````