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.

​
What You’ll Learn

In this quickstart you will:
  • Configure the Mavera Responses API using the same interface as the OpenAI SDK (base URL + API key).
  • List personas to choose an audience perspective (e.g. Gen Z Consumer, B2B Decision Maker).
  • Send a response request with a persona_id and input, and read the output and credit usage.
  • Optionally add instructions and try streaming for real-time output.
By the end you’ll have a working request in your language of choice and know where to go next.
Time: About 5 minutes. Credits: A single response typically uses 1–5 credits depending on input length.

​
Prerequisites

Before you begin, ensure you have:
A Mavera account with an active subscription. Sign up at app.mavera.io.
An API key from Developer Settings. Keys start with mvra_live_.
A way to run code or HTTP requests: Python 3.8+, Node.js 18+, or a terminal for cURL.
If you don’t have an API key yet, use the main Quickstart to create one in under a minute.

​
Step 1: Install the Client (Python or JavaScript)

The Mavera Responses API is compatible with the official OpenAI SDKs. You only need to point the client at Mavera’s base URL and use your Mavera API key.

​
Python

pip install openai

​
JavaScript / Node.js

npm install openai

​
cURL

No installation beyond a terminal. Use the base URL and pass your API key in the Authorization header.
For production, use environment variables for your API key (e.g. MAVERA_API_KEY). See Authentication for patterns.

​
Step 2: Create the Client and Set the Base URL

Configure the OpenAI client to use Mavera’s endpoint. The only Mavera-specific change is the base URL; the rest of the API matches OpenAI’s Responses API. 
from openai import OpenAI

client = OpenAI(
    api_key="mvra_live_your_key_here",
    base_url="https://app.mavera.io/api/v1",
)
Replace mvra_live_your_key_here with your real API key. Never commit keys to version control or expose them in client-side (browser) code.

​
Step 3: Get a Persona ID

Every response is improved by a persona: a predefined audience perspective (e.g. generational, professional, or industry) that shapes the tone and content of the output. You pass a persona_id in each request. First, list available personas to find one that fits your use case: 
import requests

response = requests.get(
    "https://app.mavera.io/api/v1/personas",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
)
data = response.json()

for persona in data["data"][:8]:
    print(f"{persona['name']} ({persona['category']}): {persona['id']}")
Example response (trimmed): 
{
  "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 one id (e.g. clx1abc2d0001abcdef123456) to use in the next step. Listing personas does not consume credits.

​
Step 4: Send Your First Response

Send a user input with the chosen persona_id. In Python you must pass Mavera-specific fields (like persona_id) via extra_body because they are not part of the standard OpenAI type definitions. In JavaScript, you can add persona_id directly to the request object. 
response = client.responses.create(
    model="mavera-1",
    input="What matters most when choosing a laptop for work?",
    extra_body={"persona_id": "clx1abc2d0001abcdef123456"},
)

message = response.output[0].content[0].text
credits = response.usage.credits_used

print(message)
print(f"\nCredits used: {credits}")
You should see a text response tailored to the persona (e.g. Gen Z vs B2B) and a usage.credits_used value (typically 1–5 for a short exchange).
Model: Use mavera-1 for responses. Persona: If you omit persona_id, the API may reject the request or use a default depending on your account; always passing a valid persona_id is recommended.

​
Step 5: Add Instructions (Optional)

You can use the instructions parameter to set context or role instructions. The persona still drives the audience perspective; instructions drives role or task. 
response = client.responses.create(
    model="mavera-1",
    input="What matters most when choosing a laptop for work?",
    instructions="You are a helpful product advisor. Keep answers to 2–3 sentences.",
    extra_body={"persona_id": "clx1abc2d0001abcdef123456"},
)
print(response.output[0].content[0].text)

​
Step 6: Try Streaming (Optional)

For longer answers or a better UX, request a streaming response. Tokens are returned as they’re generated. 
with client.responses.stream(
    model="mavera-1",
    input="List three benefits of remote work in one sentence each.",
    extra_body={"persona_id": "clx1abc2d0001abcdef123456"},
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
print()
Streaming uses the same credit logic as non-streaming; you’re charged for the full response.

​
Understanding the Response

A successful response includes:
FieldDescription
output[0].content[0].textThe assistant’s text reply.
output[0].roleAlways "assistant" for the reply.
status"completed" when the reply is complete.
usage.input_tokensInput tokens used.
usage.output_tokensOutput tokens used.
usage.credits_usedMavera-specific. Credits consumed by this request (typically 1–5 for simple requests).
Example (simplified): 
{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "mavera-1",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "For work, I care most about reliability, battery life, and a good keyboard..."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 28,
    "output_tokens": 52,
    "credits_used": 2
  }
}

​
Common Issues

Confirm your key starts with mvra_live_ and is copied correctly. Check Authentication and ensure the key is not revoked in Developer Settings.
Use an id from GET /personas. Ensure the value is a string and that the persona exists in your account (e.g. not from another workspace).
Use extra_body={"persona_id": "..."} in responses.create(). The OpenAI Python SDK does not expose Mavera fields on the method signature, so they must go in extra_body.
Your account has no credits left. Add credits or wait for the next billing cycle. See Credits and Error Handling.

​
Next Steps

Responses API

Streaming, analysis mode, structured outputs, tool calling, and images

Personas

Pre-built and custom personas, categories, and creation pipelines

Authentication

API key security, rotation, and environment variables

API Reference

Full request/response specification for the Responses API
Once you’re comfortable with a single response, try Quickstart: Mave Agent for multi-source research, or Quickstart: Focus Groups for synthetic survey responses.