upriver-ai Trends Radar (Beta) API

openapi: 3.2.0
info:
  title: Upriver Trends Radar (Beta) 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
tags:
- name: Trends Radar (Beta)
paths:
  /v2/radar:
    get:
      tags:
      - Trends Radar (Beta)
      summary: List trends, topics, and breakouts (Beta)
      operationId: list_radar_beta
      security:
      - APIKeyHeader: []
      parameters:
      - name: card_type
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - trend_moment
            - topic
            - entity_breakout
            type: string
          - type: 'null'
          title: Card Type
      - name: lifecycle
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by lifecycle state (e.g. rising).
          title: Lifecycle
        description: Filter by lifecycle state (e.g. rising).
      - name: program
        in: query
        required: false
        schema:
          const: general_market
          type: string
          description: Production market catalog.
          default: general_market
          title: Program
        description: Production market catalog.
      - name: persona
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter to cards serving this audience persona key.
          title: Persona
        description: Filter to cards serving this audience persona key.
      - name: entity
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter to cards featuring this brand, retailer, or product.
          title: Entity
        description: Filter to cards featuring this brand, retailer, or product.
      - name: brand_safety
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by brand-safety assessment (e.g. safe).
          title: Brand Safety
        description: Filter by brand-safety assessment (e.g. safe).
      - name: platform
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by source platform (e.g. tiktok).
          title: Platform
        description: Filter by source platform (e.g. tiktok).
      - name: min_size
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          description: Minimum number of videos on the item.
          title: Min Size
        description: Minimum number of videos on the item.
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Only items refreshed at or after this time.
          title: Since
        description: Only items refreshed at or after this time.
      - name: sort
        in: query
        required: false
        schema:
          enum:
          - rising
          - momentum
          - newest
          - value
          - freshness
          - size
          type: string
          description: Ranking mode. Rising orders items accelerating relative to their own recent baseline. The legacy momentum value remains accepted.
          default: rising
          title: Sort
        description: Ranking mode. Rising orders items accelerating relative to their own recent baseline. The legacy momentum value remains accepted.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 25
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Pagination offset.
          default: 0
          title: Offset
        description: Pagination offset.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RadarListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-mint:
        metadata:
          tag: BETA
  /v2/radar/breakouts:
    get:
      tags:
      - Trends Radar (Beta)
      summary: List product/brand breakouts (Beta)
      operationId: list_radar_breakouts_beta
      security:
      - APIKeyHeader: []
      parameters:
      - name: lifecycle
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Lifecycle
      - name: program
        in: query
        required: false
        schema:
          const: general_market
          type: string
          default: general_market
          title: Program
      - name: persona
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Persona
      - name: entity
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Entity
      - name: brand_safety
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand Safety
      - name: platform
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform
      - name: min_size
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          title: Min Size
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Since
      - name: sort
        in: query
        required: false
        schema:
          enum:
          - rising
          - momentum
          - newest
          - value
          - freshness
          - size
          type: string
          default: rising
          title: Sort
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 25
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RadarListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-mint:
        metadata:
          tag: BETA
  /v2/radar/facets:
    get:
      tags:
      - Trends Radar (Beta)
      summary: List valid filter values (Beta)
      description: 'Filters are exact-match; this is how callers learn legal values

        (e.g. the persona key is ``teacher``, not ``teachers``).'
      operationId: get_radar_facets_beta
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RadarFacetsResponse'
      security:
      - APIKeyHeader: []
      x-mint:
        metadata:
          tag: BETA
  /v2/radar/items/{item_id}:
    get:
      tags:
      - Trends Radar (Beta)
      summary: Get one radar item with live stats (Beta)
      operationId: get_radar_item_beta
      security:
      - APIKeyHeader: []
      parameters:
      - name: item_id
        in: path
        required: true
        schema:
          type: string
          title: Item Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RadarItemResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-mint:
        metadata:
          tag: BETA
  /v2/radar/search:
    post:
      tags:
      - Trends Radar (Beta)
      summary: Search the radar by natural language (Beta)
      operationId: search_radar_beta
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RadarSearchInput'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RadarSearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-mint:
        metadata:
          tag: BETA
  /v2/radar/topics:
    get:
      tags:
      - Trends Radar (Beta)
      summary: List durable topics (Beta)
      operationId: list_radar_topics_beta
      security:
      - APIKeyHeader: []
      parameters:
      - name: lifecycle
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Lifecycle
      - name: program
        in: query
        required: false
        schema:
          const: general_market
          type: string
          default: general_market
          title: Program
      - name: persona
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Persona
      - name: entity
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Entity
      - name: brand_safety
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand Safety
      - name: platform
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform
      - name: min_size
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          title: Min Size
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Since
      - name: sort
        in: query
        required: false
        schema:
          enum:
          - rising
          - momentum
          - newest
          - value
          - freshness
          - size
          type: string
          default: rising
          title: Sort
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 25
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RadarListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-mint:
        metadata:
          tag: BETA
  /v2/radar/trends:
    get:
      tags:
      - Trends Radar (Beta)
      summary: List trend moments (Beta)
      operationId: list_radar_trends_beta
      security:
      - APIKeyHeader: []
      parameters:
      - name: lifecycle
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Lifecycle
      - name: program
        in: query
        required: false
        schema:
          const: general_market
          type: string
          default: general_market
          title: Program
      - name: persona
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Persona
      - name: entity
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Entity
      - name: brand_safety
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand Safety
      - name: platform
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform
      - name: min_size
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          title: Min Size
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Since
      - name: sort
        in: query
        required: false
        schema:
          enum:
          - rising
          - momentum
          - newest
          - value
          - freshness
          - size
          type: string
          default: rising
          title: Sort
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 25
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RadarListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-mint:
        metadata:
          tag: BETA
components:
  schemas:
    RadarItemResponse:
      properties:
        beta:
          type: string
          title: Beta
          description: Beta status caveat.
          default: 'Beta: response shapes may change and this surface may converge with /v2/trends.'
        item:
          $ref: '#/components/schemas/RadarItem'
          description: The requested item with live stats.
      type: object
      required:
      - item
      title: RadarItemResponse
    RadarListResponse:
      properties:
        beta:
          type: string
          title: Beta
          description: Beta status caveat.
          default: 'Beta: response shapes may change and this surface may converge with /v2/trends.'
        items:
          items:
            $ref: '#/components/schemas/RadarItem'
          type: array
          title: Items
          description: Items matching the query.
        total:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total
          description: Total items matching the filters, across all pages.
      type: object
      required:
      - items
      title: RadarListResponse
    RadarSearchResult:
      properties:
        item:
          $ref: '#/components/schemas/RadarItem'
        match_score:
          type: number
          title: Match Score
          description: Semantic match strength for the query.
      type: object
      required:
      - item
      - match_score
      title: RadarSearchResult
    FacetValue:
      properties:
        value:
          type: string
          title: Value
          description: The filter value to pass in queries.
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
          description: Display label.
        count:
          type: integer
          title: Count
          description: Items currently carrying this value.
      type: object
      required:
      - value
      - count
      title: FacetValue
    RadarSearchInput:
      properties:
        query:
          type: string
          maxLength: 500
          minLength: 2
          title: Query
          description: Natural-language description of the trend, topic, or audience.
        limit:
          type: integer
          maximum: 50.0
          minimum: 1.0
          title: Limit
          default: 10
        card_type:
          anyOf:
          - type: string
            enum:
            - trend_moment
            - topic
            - entity_breakout
          - type: 'null'
          title: Card Type
          description: Restrict results to one item type.
        program:
          type: string
          const: general_market
          title: Program
          description: Production market catalog searched for results.
          default: general_market
        lifecycle:
          anyOf:
          - type: string
          - type: 'null'
          title: Lifecycle
          description: Restrict results to one lifecycle state.
        brand_safety:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand Safety
          description: Restrict results by brand-safety assessment.
      type: object
      required:
      - query
      title: RadarSearchInput
    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
    RadarFacetsResponse:
      properties:
        beta:
          type: string
          title: Beta
          description: Beta status caveat.
          default: 'Beta: response shapes may change and this surface may converge with /v2/trends.'
        types:
          items:
            type: string
          type: array
          title: Types
          description: Item types for the type filter.
        programs:
          items:
            $ref: '#/components/schemas/FacetValue'
          type: array
          title: Programs
          description: Available market catalogs.
        lifecycle_states:
          items:
            $ref: '#/components/schemas/FacetValue'
          type: array
          title: Lifecycle States
          description: Lifecycle values.
        personas:
          items:
            $ref: '#/components/schemas/FacetValue'
          type: array
          title: Personas
          description: Audience persona keys.
        brand_safety:
          items:
            $ref: '#/components/schemas/FacetValue'
          type: array
          title: Brand Safety
          description: Brand-safety values.
        sorts:
          items:
            type: string
          type: array
          title: Sorts
          description: Valid sort values for list calls.
      type: object
      required:
      - types
      - programs
      - lifecycle_states
      - personas
      - brand_safety
      - sorts
      title: RadarFacetsResponse
      description: 'Legal filter vocabularies — filters are exact-match, so callers

        need a way to learn valid values instead of guessing.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RadarItem:
      properties:
        id:
          type: string
          title: Id
          description: Stable item identifier.
        type:
          type: string
          enum:
          - trend_moment
          - topic
          - entity_breakout
          title: Type
          description: 'trend_moment: a participatory trend moment. topic: a durable subject area. entity_breakout: a product or brand gaining attention.'
        name:
          type: string
          title: Name
          description: Human-readable card title.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: One-sentence summary of what the card covers.
        insight:
          anyOf:
          - type: string
          - type: 'null'
          title: Insight
          description: Analyst note on what is driving this right now.
        how_to_act:
          anyOf:
          - type: string
          - type: 'null'
          title: How To Act
          description: Suggested content, product, or campaign activation angle.
        brand_safety:
          anyOf:
          - type: string
          - type: 'null'
          title: Brand Safety
          description: 'Brand-safety assessment: safe, caution, unsafe.'
        lifecycle_state:
          anyOf:
          - type: string
          - type: 'null'
          title: Lifecycle State
          description: 'Where the card sits in its lifecycle: emerging, rising, peaking, steady, or declining.'
        momentum_ratio:
          anyOf:
          - type: number
          - type: 'null'
          title: Momentum Ratio
          description: Recent activity relative to the card's own baseline.
        value_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Value Score
          description: Composite quality/opportunity score.
        stats:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Stats
          description: 'Live evaluation stats: video and creator counts, freshness, audience and format composition, publishing activity, and the collection scope in which supporting videos were observed. Optional presentation_formats list caption-based format names and their evidence_basis: caption_label, caption_description, or mixed. Optional examples list sample videos with tiktok_id, url, caption, creator, views, published_at, and cover_url: a temporary image URL to load directly, or null when no image is available. Optional activity.catch_corrected (version cpf-v1) corrects weekly posts for how likely our searches were to find them. Lists, search and item detail carry its version, estimable, reason (when not estimable), momentum (the corrected lifecycle reading, or null) and momentum_raw (the reading from found counts). When momentum is non-null, lifecycle_state and momentum_ratio equal its state and ratio; otherwise they come from found counts (momentum_raw). Item detail adds weekly arrays from start_week: observed (videos found), a range from estimate (posts our searches can reach) to estimate_with_quiet (also counting rarely shown videos), low and high (an 80% sampling band), and catch_chance; null weeks can''t be estimated, and the last still_found_weeks weeks are still being found.'
        personas:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Personas
          description: Audience personas this card serves, with strength.
        program:
          anyOf:
          - type: string
          - type: 'null'
          title: Program
          description: Market catalog this item belongs to.
        first_seen:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: First Seen
          description: When this item first appeared on the radar.
        last_updated:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Updated
          description: When this item's stats were last refreshed.
        archived:
          type: boolean
          title: Archived
          description: True when the item is no longer tracked; archived items are excluded from lists and search.
          default: false
      type: object
      required:
      - id
      - type
      - name
      title: RadarItem
      description: 'One card: a named slice of cultural activity with its live stats.'
    RadarSearchResponse:
      properties:
        beta:
          type: string
          title: Beta
          description: Beta status caveat.
          default: 'Beta: response shapes may change and this surface may converge with /v2/trends.'
        results:
          items:
            $ref: '#/components/schemas/RadarSearchResult'
          type: array
          title: Results
      type: object
      required:
      - results
      title: RadarSearchResponse
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key