Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mavera.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Scenario

Your best customers describe your product in their own words on Trustpilot — and those words are often better than anything your marketing team writes. You pull 4-5 star reviews, extract the language patterns, and feed them into Mavera’s Brand Voice engine. The result is a voice profile that mirrors how satisfied customers actually talk about you. Flow: Trustpilot GET /business-units/{id}/reviews (stars 4-5) → Extract review text → Mavera POST /brand-voices → Customer-grounded voice profile

​
Architecture

​
Code

import os, requests, time
from openai import OpenAI

TP_KEY = os.environ["TRUSTPILOT_API_KEY"]
MV = os.environ["MAVERA_API_KEY"]
BU_ID = os.environ["TRUSTPILOT_BU_ID"]
TP_BASE = "https://api.trustpilot.com/v1"
MV_BASE = "https://app.mavera.io/api/v1"
MV_H = {"Authorization": f"Bearer {MV}", "Content-Type": "application/json"}

# 1. Pull 4-5 star reviews
reviews = []
for stars in [5, 4]:
    page = 1
    while len(reviews) < 100:
        r = requests.get(f"{TP_BASE}/business-units/{BU_ID}/reviews",
            params={"apikey": TP_KEY, "stars": stars, "perPage": 50, "page": page,
                     "orderBy": "createdat.desc"})
        if r.status_code == 429:
            time.sleep(2)
            continue
        r.raise_for_status()
        data = r.json()
        batch = data.get("reviews", [])
        if not batch:
            break
        reviews.extend(batch)
        page += 1
        time.sleep(0.2)

# 2. Extract review text
samples = []
for rev in reviews:
    title = rev.get("title", "")
    text = rev.get("text", "")
    stars = rev.get("stars", 0)
    if text and len(text) > 50:
        samples.append(f"[{stars}★] {title}\n{text}")

# 3. Create Brand Voice
combined = "\n\n---\n\n".join(samples[:20])

bv = requests.post(f"{MV_BASE}/brand-voices", headers=MV_H, json={
    "name": "Trustpilot Customer Voice",
    "samples": [combined],
}).json()
print(f"Brand Voice: {bv['id']}")

# 4. Wait for processing
time.sleep(3)
detail = requests.get(f"{MV_BASE}/brand-voices/{bv['id']}", headers=MV_H).json()
print(f"Status: {detail.get('status', 'unknown')}")

# 5. Test generation
mavera = OpenAI(api_key=MV, base_url=MV_BASE)
test = mavera.responses.create(model="mavera-1",
    input=[{"role": "user", "content": "Write a 100-word homepage hero paragraph."}],
    extra_body={"brand_voice_id": bv["id"]})
print(f"\n{test.output[0].content[0].text}")

​
Example Output

Brand Voice: bv_tp_cust_4k7m (status: ready)

We built this because we were tired of guessing. Tired of launching campaigns
and hoping the message landed. Our customers — from two-person startups to
Fortune 500 marketing teams — tell us the same thing: "It just works."
Set up takes minutes. Your first insight comes before lunch. And every piece
of content you create from here carries the voice your audience already trusts.

​
Error Handling

Public review endpoints use ?apikey={key}. Business/private endpoints (reply, flag) require OAuth 2.0. Use OAuth for Job 5 (review responses).
Pass stars as a query param. For multiple stars, make separate requests (Trustpilot doesn’t support stars=4,5 in a single call).
One-line reviews like “Great service!” don’t contribute meaningful voice data. Filter reviews under 50 characters.