Quickstart: Responses API

Get your first persona-powered response in under 5 minutes with Python, JavaScript, or cURL

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.

Python

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:

Python

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.

Python

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.

Python

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.

Python

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:

Field	Description
output[0].content[0].text	The assistant’s text reply.
output[0].role	Always "assistant" for the reply.
status	"completed" when the reply is complete.
usage.input_tokens	Input tokens used.
usage.output_tokens	Output tokens used.
usage.credits_used	Mavera-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

401 Unauthorized or invalid_api_key

Confirm your key starts with mvra_live_ and is copied correctly. Check Authentication and ensure the key is not revoked in Developer Settings.

Invalid or missing persona_id

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).

Python: persona_id or extra_body not working

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.

402 Payment Required / credits_exhausted

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.