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

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

<Info>
  **Time:** About 5 minutes. **Credits:** A single response typically uses 1–5 credits depending on input length.
</Info>

***

## Prerequisites

Before you begin, ensure you have:

<Check>**A Mavera account** with an active subscription. Sign up at [app.mavera.io](https://app.mavera.io).</Check>
<Check>**An API key** from [Developer Settings](https://app.mavera.io/settings/developer). Keys start with `mvra_live_`.</Check>
<Check>**A way to run code or HTTP requests:** Python 3.8+, Node.js 18+, or a terminal for cURL.</Check>

If you don't have an API key yet, use the main [Quickstart](/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

```bash theme={"dark"}
pip install openai
```

### JavaScript / Node.js

```bash theme={"dark"}
npm install openai
```

### cURL

No installation beyond a terminal. Use the base URL and pass your API key in the `Authorization` header.

<Tip>
  For production, use environment variables for your API key (e.g. `MAVERA_API_KEY`). See [Authentication](/guides/authentication#environment-variables) for patterns.
</Tip>

***

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

<CodeGroup>
  ```python Python theme={"dark"}
  from openai import OpenAI

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

  ```javascript JavaScript theme={"dark"}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: "mvra_live_your_key_here",
    baseURL: "https://app.mavera.io/api/v1",
  });
  ```

  ```go Go theme={"dark"}
  import "github.com/sashabaranov/go-openai"

  config := openai.DefaultConfig("mvra_live_your_key_here")
  config.BaseURL = "https://app.mavera.io/api/v1"
  client := openai.NewClientWithConfig(config)
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

***

## 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:

<CodeGroup>
  ```python Python theme={"dark"}
  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']}")
  ```

  ```javascript JavaScript theme={"dark"}
  const response = await fetch("https://app.mavera.io/api/v1/personas", {
    headers: { Authorization: "Bearer mvra_live_your_key_here" },
  });
  const { data: personas } = await response.json();

  personas.slice(0, 8).forEach((p) => {
    console.log(`${p.name} (${p.category}): ${p.id}`);
  });
  ```

  ```bash cURL theme={"dark"}
  curl -s https://app.mavera.io/api/v1/personas \
    -H "Authorization: Bearer mvra_live_your_key_here" | jq '.data[:5] | .[] | {name, category, id}'
  ```
</CodeGroup>

Example response (trimmed):

```json theme={"dark"}
{
  "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.

<CodeGroup>
  ```python Python theme={"dark"}
  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}")
  ```

  ```javascript JavaScript theme={"dark"}
  const response = await client.responses.create({
    model: "mavera-1",
    input: "What matters most when choosing a laptop for work?",
    // @ts-ignore - Mavera custom field
    persona_id: "clx1abc2d0001abcdef123456",
  });

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

  console.log(message);
  console.log(`\nCredits used: ${credits}`);
  ```

  ```bash cURL theme={"dark"}
  curl -X POST https://app.mavera.io/api/v1/responses \
    -H "Authorization: Bearer mvra_live_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "mavera-1",
      "persona_id": "clx1abc2d0001abcdef123456",
      "input": "What matters most when choosing a laptop for work?"
    }'
  ```
</CodeGroup>

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

<Info>
  **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.
</Info>

***

## 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*.

<CodeGroup>
  ```python Python theme={"dark"}
  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)
  ```

  ```javascript JavaScript theme={"dark"}
  const response = await 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.",
    // @ts-ignore - Mavera custom field
    persona_id: "clx1abc2d0001abcdef123456",
  });
  console.log(response.output[0].content[0].text);
  ```
</CodeGroup>

***

## Step 6: Try Streaming (Optional)

For longer answers or a better UX, request a **streaming** response. Tokens are returned as they're generated.

<CodeGroup>
  ```python Python theme={"dark"}
  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()
  ```

  ```javascript JavaScript theme={"dark"}
  const stream = client.responses.stream({
    model: "mavera-1",
    input: "List three benefits of remote work in one sentence each.",
    // @ts-ignore - Mavera custom field
    persona_id: "clx1abc2d0001abcdef123456",
  });

  for await (const event of stream) {
    if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    }
  }
  console.log();
  ```
</CodeGroup>

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

```json theme={"dark"}
{
  "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

<AccordionGroup>
  <Accordion title="401 Unauthorized or invalid_api_key">
    Confirm your key starts with `mvra_live_` and is copied correctly. Check [Authentication](/guides/authentication) and ensure the key is not revoked in [Developer Settings](https://app.mavera.io/settings/developer).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="402 Payment Required / credits_exhausted">
    Your account has no credits left. Add credits or wait for the next billing cycle. See [Credits](/guides/credits) and [Error Handling](/guides/errors#credit-errors-402).
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Responses API" icon="comments" href="/features/responses">
    Streaming, analysis mode, structured outputs, tool calling, and images
  </Card>

  <Card title="Personas" icon="user" href="/features/personas">
    Pre-built and custom personas, categories, and creation pipelines
  </Card>

  <Card title="Authentication" icon="key" href="/guides/authentication">
    API key security, rotation, and environment variables
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/responses/create-a-response">
    Full request/response specification for the Responses API
  </Card>
</CardGroup>

Once you're comfortable with a single response, try [Quickstart: Mave Agent](/quickstart-mave) for multi-source research, or [Quickstart: Focus Groups](/quickstart-focus-groups) for synthetic survey responses.