Skip to content
UpriverUpriverUpriver API Docs

Dimensions

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

Dimensions

​

Extract atomic audience dimensions for a brand. Dimensions are the building blocks of personas.

Returns granular behavioral, motivational, and lifestyle dimensions about relevant audiences for a specified brand. Each fact can be used for matching with user profiles.

Verbosity controls fact phrasing (applies only to the fact field):

  • verbose: Full sentences with subject (e.g., 'This audience seeks healthy recipes')
  • standard (default): Phrases without subject (e.g., 'seeks healthy recipes')
  • compact: Keywords only (e.g., 'healthy recipes')

Response includes:

  • Audience dimensions with classification and confidence scores
  • Supporting evidence snippets (optional)
Body·AudienceDimensionsInput
required
application/json

Input model for audience dimensions extraction.

  • brand_url
    Type: string · Brand Url
    required

    Brand website URL to analyze

  • response_config
    Type: object · AudienceDimensionsResponseConfig

    Output configuration

Responses
  • application/json
  • application/json
Request Example for post/v1/audience_dimensions
curl https://api.upriver.ai/v1/audience_dimensions \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_SECRET_TOKEN' \
  --data '{
  "brand_url": "https://drinkolipop.com",
  "response_config": {
    "include_rollup": false,
    "verbosity": "standard",
    "metadata_mode": "basic",
    "max_results": 5,
    "min_confidence": 0.55,
    "max_facts": 25,
    "min_fact_confidence": 0.3,
    "include_evidence_snippets": true,
    "max_snippets_per_fact": 3
  }
}'

{
  "meta": {
    "generated_at": "2026-09-05T06:49:26.587Z",
    "industries": [
      "string"
    ],
    "continuation_token": "string",
    "counts": {
      "total": 1,
      "by_scope": {
        "general": 0,
        "multi_platform": 0,
        "platform_specific": 0
      }
    },
    "source_filters": {
      "platforms": [
        "string"
      ],
      "source_names": [
        "string"
      ],
      "source_urls": [
        "https://example.com"
      ],
      "restriction": "none"
    },
    "debug_info": {
      "duration_ms": 1,
      "candidates_before_filter": 1,
      "applied_filters": [
        {
          "name": "string",
          "value": null,
          "reason": "string"
        }
      ]
    },
    "sources_analyzed": [
      "string"
    ],
    "content_analyzed_count": 0,
    "pipeline_version": "string"
  },
  "brand_name": "string",
  "brand_url": "string",
  "facts": [
    {
      "fact": "This audience seeks healthier alternatives to sugary drinks",
      "dimension": "behavior",
      "tier": "long_tail",
      "confidence": 0,
      "source_count": 1,
      "example_sources": [
        "string"
      ],
      "evidence_snippets": [
        {
          "source_id": "string",
          "source": "string",
          "title": "string",
          "text_snippet": "string",
          "url": "string"
        }
      ]
    }
  ]
}

Successful Response