Skip to content
UpriverUpriverUpriver API Docs

Get Narrative

v1.0.0
OpenAPI 3.1.0

Upriver API

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.

Server:https://api.upriver.ai

Production API server

Client Libraries
Shell Curl

Get Narrative

​

Get a narrative by ID with member topics.

Path Parameters
  • narrative_id
    Type: string · Narrative Id
    required

    Narrative UUID returned by GET /v1/topics/breakout/narratives.

Query Parameters
  • include
    Type: array string[] · Includeenum

    Optional expansions to include on member topics. Allowed values: citations, entities. Example: include=citations&include=entities

    values
    • citations
    • entities
  • feed
    Type: string · Feednullable

    Entitled private feed that returned this narrative.

Responses
  • application/json
  • application/json
Request Example for get/v1/topics/breakout/narratives/{narrative_id}
curl 'https://api.upriver.ai/v1/topics/breakout/narratives/{narrative_id}' \
  --header 'X-API-Key: YOUR_SECRET_TOKEN'

{
  "narrative": {
    "narrative_id": "string",
    "slug": "string",
    "display_name": "string",
    "description": "string",
    "vertical": "string",
    "member_count": 1,
    "total_citations": 1,
    "combined_source_summary": {
      "additionalProperty": 1
    },
    "date_range": {
      "additionalProperty": "string"
    },
    "created_at": "2026-09-05T06:49:26.587Z",
    "updated_at": "2026-09-05T06:49:26.587Z"
  },
  "member_topics": [
    {
      "topic_id": "string",
      "topic_name": "string",
      "vertical": "string",
      "category": "string",
      "status": "string",
      "score": 1,
      "relevance_score": 1,
      "engagement": {
        "percentile_score": 1
      },
      "peak_score": 1,
      "confidence_score": 1,
      "discovered_at": "2026-09-05T06:49:26.587Z",
      "earliest_evidence_at": "2026-09-05T06:49:26.587Z",
      "last_signal_at": "2026-09-05T06:49:26.587Z",
      "updated_at": "2026-09-05T06:49:26.587Z",
      "source_summary": {
        "additionalProperty": 1
      },
      "citations": [
        {
          "source_category": "string",
          "source_url": "string",
          "title": "string",
          "display": "",
          "snippet": "string",
          "source_authority": 1,
          "engagement_score": 1,
          "published_at": "2026-09-05T06:49:26.587Z"
        }
      ],
      "entities": [
        {
          "canonical_name": "string",
          "entity_id": "string",
          "entity_type": "string",
          "confidence": 1,
          "entity_subtype": "string"
        }
      ],
      "trend": {
        "momentum": 0,
        "direction": "up"
      },
      "citation_rate": [
        {
          "day": "string",
          "count": 1
        }
      ],
      "narrative": {
        "narrative_id": "string",
        "display_name": "string",
        "member_count": 1,
        "arc_summary": [
          "string"
        ]
      },
      "temporal_status": "upcoming",
      "event_start_at": "2026-09-05T06:49:26.587Z",
      "event_end_at": "2026-09-05T06:49:26.587Z"
    }
  ]
}

Successful Response