Skip to main content
POST
/
v3
/
audience_insights
Personas (v3)
curl --request POST \
  --url https://api.upriver.ai/v3/audience_insights \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "brand_url": "<string>",
  "query": "<string>",
  "effort": "auto",
  "include_citations": true
}
'
{
  "personas": [
    {
      "label": "<string>",
      "description": "<string>",
      "purchase_motivations": [
        "<string>"
      ],
      "purchase_triggers": [
        "<string>"
      ],
      "purchase_barriers": [
        "<string>"
      ],
      "phrase_examples": [
        "<string>"
      ],
      "personality_traits": [
        {
          "id": "<string>",
          "label": "<string>"
        }
      ],
      "buying_mindset": [
        "<string>"
      ],
      "behaviors": [
        "<string>"
      ],
      "voice_and_tone": [
        "<string>"
      ],
      "communities": [
        "<string>"
      ],
      "citations": [
        {
          "title": "<string>",
          "text": "<string>",
          "url": "<string>",
          "subreddit": "<string>"
        }
      ]
    }
  ],
  "rollup_summary": "<string>",
  "meta": {
    "generated_at": "<string>"
  }
}

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
brand_url
string
required

Brand website to research.

Example:

"https://nike.com"

​
query
string | null

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
enum<string>
default:auto

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

Available options:
auto,
low,
mid,
high
​
include_citations
boolean
default:true

When true, include real world citations for each persona.

Response

Audience personas

​
personas
PersonaV3 · object[]
required

3-8 distinct audience personas.

​
rollup_summary
string | null

One-paragraph cross-persona summary (1-2 sentences).

​
meta
ResponseMetaV3 · object

Generation metadata.