Skip to content
UpriverUpriverUpriver API Docs

Personas (v3)

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

Personas (v3)

​

Get detailed audience personas for a brand.

Input: Brand URL, optional query and effort level.

Output: Personas with purchase triggers, barriers, behaviors, language patterns, and optional real world citations.

Body·GroundedInsightsInput
required
application/json
  • brand_url
    Type: string · Brand Url
    required

    Brand website to research.

  • query
    Type: string · Querynullable

    Optional query to focus the audience research on a specific topic or angle. When provided, personas will be weighted toward conversations matching this query in addition to the brand itself. For example, 'running shoes for beginners' produces personas focused on entry-level runners, while 'streetwear fashion' emphasizes style-driven audiences. When omitted, the endpoint explores the brand broadly.

  • effort
    Type: string · GroundedEffortenum

    Effort level: low, mid, high. Default is mid.

    values
    • auto
    • low
    • mid
    • high
  • include_citations
    Type: boolean · Include Citations

    When true, include real world citations for each persona.

Responses
  • application/json
  • application/json
Request Example for post/v3/audience_insights
curl https://api.upriver.ai/v3/audience_insights \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_SECRET_TOKEN' \
  --data '{
  "brand_url": "https://nike.com",
  "query": "",
  "effort": "auto",
  "include_citations": true
}'

{
  "rollup_summary": "string",
  "personas": [
    {
      "label": "string",
      "description": "string",
      "buying_mindset": [
        "string"
      ],
      "purchase_motivations": [
        "string"
      ],
      "purchase_triggers": [
        "string"
      ],
      "purchase_barriers": [
        "string"
      ],
      "phrase_examples": [
        "string"
      ],
      "communities": [
        "string"
      ],
      "citations": [
        {
          "title": "string",
          "text": "string",
          "url": "string",
          "subreddit": "string"
        }
      ]
    }
  ],
  "meta": {
    "generated_at": "string"
  }
}

Audience personas