upriver-ai Breakout Feeds API

openapi: 3.2.0
info:
  title: Upriver Breakout Feeds 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: Breakout Feeds
paths:
  /v1/breakout/feeds:
    get:
      tags:
      - Breakout Feeds
      summary: List Private Breakout Feeds
      operationId: list_private_breakout_feeds
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateFeedCatalogResponse'
      security:
      - APIKeyHeader: []
  /v1/breakout/feeds/{feed_slug}:
    get:
      tags:
      - Breakout Feeds
      summary: Get Private Breakout Feed
      operationId: get_private_breakout_feed
      security:
      - APIKeyHeader: []
      parameters:
      - name: feed_slug
        in: path
        required: true
        schema:
          type: string
          title: Feed Slug
      - name: facet
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Facet
      - name: kind
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - evidence
            - story
            - theme
            - trend
            - entity
            type: string
          - type: 'null'
          title: Kind
      - name: earliest_evidence_at_or_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Inclusive ISO 8601 lower bound for the result's `earliest_evidence_at`. Use it to restrict results to activity that first appeared within a recent window. Results with earlier dated evidence, or with no dated evidence, are excluded as a whole; evidence returned within a matching result is not time-filtered. The comparison uses all known supporting evidence, including records omitted by response filters or limits.
          title: Earliest Evidence At Or After
        description: Inclusive ISO 8601 lower bound for the result's `earliest_evidence_at`. Use it to restrict results to activity that first appeared within a recent window. Results with earlier dated evidence, or with no dated evidence, are excluded as a whole; evidence returned within a matching result is not time-filtered. The comparison uses all known supporting evidence, including records omitted by response filters or limits.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 60
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateFeedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PrivateFeedEvidenceSummary:
      properties:
        total:
          type: integer
          title: Total
        shown:
          type: integer
          title: Shown
        source_type_count:
          type: integer
          title: Source Type Count
        latest_shown_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Latest Shown At
      type: object
      required:
      - total
      - shown
      - source_type_count
      title: PrivateFeedEvidenceSummary
    FormationProjectionItemType:
      type: string
      enum:
      - evidence
      - formation
      title: FormationProjectionItemType
      description: Whether a projection row points at evidence or a formation.
    PrivateFeedObservation:
      properties:
        observed_at:
          type: string
          format: date-time
          title: Observed At
          description: When this measurement was made.
        evidence_count:
          type: integer
          title: Evidence Count
          description: Evidence count at this observation.
        source_type_count:
          type: integer
          title: Source Type Count
          description: Distinct source-type count.
        momentum_ratio:
          anyOf:
          - type: number
          - type: 'null'
          title: Momentum Ratio
          description: Recent activity relative to its baseline.
        trajectory:
          type: string
          title: Trajectory
          description: Observed direction of activity.
      type: object
      required:
      - observed_at
      - evidence_count
      - source_type_count
      - trajectory
      title: PrivateFeedObservation
    FormationIdentityState:
      type: string
      enum:
      - provisional
      - canonical
      title: FormationIdentityState
      description: Whether identity is still run-local or maintained across observations.
    PrivateFeedCatalogResponse:
      properties:
        feeds:
          items:
            $ref: '#/components/schemas/PrivateFeedSummary'
          type: array
          title: Feeds
          description: Private feeds enabled for the authenticated account.
      type: object
      required:
      - feeds
      title: PrivateFeedCatalogResponse
    PrivateFeedSummary:
      properties:
        slug:
          type: string
          title: Slug
          description: Stable private-feed identifier.
        label:
          type: string
          title: Label
          description: Human-readable private-feed label.
        facets:
          items:
            $ref: '#/components/schemas/PrivateFeedFacet'
          type: array
          title: Facets
          description: Available feed facets.
        presentation_source:
          type: string
          enum:
          - curated
          - breakout
          title: Presentation Source
          description: Content source used to present this feed.
        breakout_vertical:
          anyOf:
          - type: string
          - type: 'null'
          title: Breakout Vertical
          description: Breakout vertical used when this feed presents Breakout content.
      type: object
      required:
      - slug
      - label
      - facets
      - presentation_source
      title: PrivateFeedSummary
    FormationKind:
      type: string
      enum:
      - story
      - theme
      - topic
      - trend
      - entity
      title: FormationKind
      description: What an observed formation represents.
    PrivateFeedFacet:
      properties:
        slug:
          type: string
          title: Slug
          description: Stable feed facet identifier.
        label:
          type: string
          title: Label
          description: Human-readable facet label.
      type: object
      required:
      - slug
      - label
      title: PrivateFeedFacet
    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
    PrivateFeedItem:
      properties:
        item_id:
          type: string
          title: Item Id
        parent_item_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Item Id
        item_type:
          $ref: '#/components/schemas/FormationProjectionItemType'
        facet:
          type: string
          title: Facet
        facet_label:
          type: string
          title: Facet Label
        headline:
          type: string
          title: Headline
        why_relevant:
          type: string
          title: Why Relevant
        why_now:
          type: string
          title: Why Now
        overall_rank:
          anyOf:
          - type: integer
          - type: 'null'
          title: Overall Rank
        facet_rank:
          type: integer
          title: Facet Rank
        earliest_evidence_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Earliest Evidence At
          description: Earliest publication time among known dated evidence supporting this result; a proxy for when the underlying activity began.
        evidence_summary:
          $ref: '#/components/schemas/PrivateFeedEvidenceSummary'
        evidence:
          anyOf:
          - $ref: '#/components/schemas/PrivateFeedEvidence'
          - type: 'null'
        formation:
          anyOf:
          - $ref: '#/components/schemas/PrivateFeedFormation'
          - type: 'null'
      type: object
      required:
      - item_id
      - item_type
      - facet
      - facet_label
      - headline
      - why_relevant
      - why_now
      - facet_rank
      - evidence_summary
      title: PrivateFeedItem
    PrivateFeedFormation:
      properties:
        formation_id:
          type: string
          title: Formation Id
        kind:
          $ref: '#/components/schemas/FormationKind'
        identity_state:
          $ref: '#/components/schemas/FormationIdentityState'
        title:
          type: string
          title: Title
        summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Summary
        maturity:
          anyOf:
          - type: string
            enum:
            - watchlist
            - established
          - type: 'null'
          title: Maturity
        entities:
          items:
            type: string
          type: array
          title: Entities
        first_seen:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: First Seen
        last_seen:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Seen
        evidence:
          items:
            $ref: '#/components/schemas/PrivateFeedEvidence'
          type: array
          title: Evidence
        observations:
          items:
            $ref: '#/components/schemas/PrivateFeedObservation'
          type: array
          title: Observations
      type: object
      required:
      - formation_id
      - kind
      - identity_state
      - title
      - entities
      - evidence
      - observations
      title: PrivateFeedFormation
    PrivateFeedResponse:
      properties:
        feed:
          $ref: '#/components/schemas/PrivateFeedSummary'
        generated_at:
          type: string
          format: date-time
          title: Generated At
        lookback_days:
          type: integer
          title: Lookback Days
        items:
          items:
            $ref: '#/components/schemas/PrivateFeedItem'
          type: array
          title: Items
      type: object
      required:
      - feed
      - generated_at
      - lookback_days
      - items
      title: PrivateFeedResponse
    PrivateFeedEvidence:
      properties:
        evidence_id:
          type: string
          title: Evidence Id
          description: Stable source evidence identifier.
        source_type:
          type: string
          title: Source Type
          description: Kind of source containing the evidence.
        source_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Url
          description: Link to the evidence.
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
          description: Evidence title when present.
        excerpt:
          anyOf:
          - type: string
          - type: 'null'
          title: Excerpt
          description: Short evidence excerpt.
        author_handle:
          anyOf:
          - type: string
          - type: 'null'
          title: Author Handle
          description: Public author handle when present.
        community:
          anyOf:
          - type: string
          - type: 'null'
          title: Community
          description: Community containing the evidence.
        published_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Published At
          description: When the evidence was published.
        claims:
          items:
            $ref: '#/components/schemas/PrivateFeedEvidenceClaim'
          type: array
          title: Claims
          description: Numbers this evidence states about its own subject, quoted from its text. Empty when it states none, when the figures could not be established, or when the text changed after they were read.
      type: object
      required:
      - evidence_id
      - source_type
      title: PrivateFeedEvidence
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PrivateFeedEvidenceClaim:
      properties:
        quantity:
          type: string
          title: Quantity
          description: The figure exactly as the evidence states it.
        subject:
          type: string
          title: Subject
          description: What the figure refers to, in the evidence's own words.
      type: object
      required:
      - quantity
      - subject
      title: PrivateFeedEvidenceClaim
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key