Skip to main content

​
Prerequisites

Before you begin, you’ll need:
A Mavera account with an active subscription
An API key from your Developer Settings

​
Step 1: Get Your API Key

1

Go to Developer Settings

Navigate to app.mavera.io/settings/developer
2

Create API Key

Click Create API Key and give it a descriptive name
3

Copy Your Key

Copy the key immediately — it won’t be shown again. Keys start with mvra_live_
Keep your API key secure. Never commit it to version control or expose it in client-side code.

​
Step 2: Get a Persona ID

Every response request benefits from a persona. List available personas to find one that fits your use case: 
curl https://app.mavera.io/api/v1/personas \
  -H "Authorization: Bearer mvra_live_your_key_here"
Example response: 
{
  "data": [
    {
      "id": "clx1abc2d0001abcdef123456",
      "name": "Gen Z Consumer",
      "category": "Generational",
      "description": "Digital native, values authenticity and social responsibility..."
    },
    {
      "id": "clx2def3e0002ghijkl789012",
      "name": "B2B Decision Maker",
      "category": "Professional",
      "description": "Senior executive focused on ROI and strategic value..."
    }
  ]
}
Copy the id of a persona you want to use.

​
Step 3: Make Your First Request

Now use the persona in a response request: 
from openai import OpenAI

client = OpenAI(
    api_key="mvra_live_your_key_here",
    base_url="https://app.mavera.io/api/v1",
)

response = client.responses.create(
    model="mavera-1",
    input="What matters most when choosing a laptop?",
    extra_body={"persona_id": "clx1abc2d0001abcdef123456"},
)

print(response.output[0].content[0].text)
print(f"Credits used: {response.usage.credits_used}")
The response includes usage.credits_used so you can track your consumption in real-time.

​
Step 4: Try Mave Agent (Optional)

For comprehensive research with multiple sources, use the Mave agent: 
import requests

response = requests.post(
    "https://app.mavera.io/api/v1/mave/chat",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    json={
        "message": "Analyze the competitive landscape for electric vehicles in Europe"
    }
)

result = response.json()
print(f"Thread ID: {result['thread_id']}")
print(f"Response: {result['content'][:500]}...")
print(f"Sources: {len(result['sources'])} references")
print(f"Credits used: {result['usage']['credits_used']}")
Mave conducts multi-phase research and returns comprehensive analysis with sources, thread ID for follow-up questions, and personas used.

​
Feature quick starts

Go deeper with step-by-step guides for each major API:

Quickstart: Chat

Persona-powered responses in 5 minutes (Python, JavaScript, cURL)

Quickstart: Mave Agent

First research query with sources and thread follow-ups

Quickstart: Focus Groups

Create and run a synthetic focus group with NPS and Likert

Quickstart: Video Analysis

Upload a video and get emotional and engagement metrics

​
Next Steps

Authentication

Learn about API key security and best practices

Rate Limits

Understand rate limiting and how to handle it

Responses API

Deep dive into the Responses API with personas

API Reference

Explore all available endpoints

​
SDK Compatibility

Mavera’s Responses API is compatible with OpenAI SDKs. Just change the base URL and use client.responses.create():
LanguageSDKBase URL Override
Pythonopenaibase_url="https://app.mavera.io/api/v1"
JavaScriptopenaibaseURL: "https://app.mavera.io/api/v1"
Gogo-openaiSet BaseURL in config
AnyRESTUse https://app.mavera.io/api/v1 directly
The persona_id field is Mavera-specific. In Python, pass it via extra_body in responses.create(). In JavaScript/TypeScript, add it directly to the request object. Use input instead of messages for your prompt.