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

> Get started with the Mavera API in under 5 minutes

## Prerequisites

Before you begin, you'll need:

<Check>A Mavera account with an active subscription</Check>
<Check>An API key from your [Developer Settings](https://app.mavera.io/settings/developer)</Check>

## Step 1: Get Your API Key

<Steps>
  <Step title="Go to Developer Settings">
    Navigate to [app.mavera.io/settings/developer](https://app.mavera.io/settings/developer)
  </Step>

  <Step title="Create API Key">
    Click **Create API Key** and give it a descriptive name
  </Step>

  <Step title="Copy Your Key">
    Copy the key immediately — it won't be shown again. Keys start with `mvra_live_`
  </Step>
</Steps>

<Warning>
  Keep your API key secure. Never commit it to version control or expose it in client-side code.
</Warning>

## Step 2: Get a Persona ID

Every response request benefits from a persona. List available personas to find one that fits your use case:

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl https://app.mavera.io/api/v1/personas \
    -H "Authorization: Bearer mvra_live_your_key_here"
  ```

  ```python Python theme={"dark"}
  import requests

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

  personas = response.json()["data"]
  for persona in personas[:5]:
      print(f"{persona['name']}: {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, 5).forEach((p) => console.log(`${p.name}: ${p.id}`));
  ```
</CodeGroup>

Example response:

```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 the `id` of a persona you want to use.

## Step 3: Make Your First Request

Now use the persona in a response request:

<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",
  )

  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}")
  ```

  ```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",
  });

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

  console.log(response.output[0].content[0].text);
  console.log("Credits used:", response.usage.credits_used);
  ```

  ```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?"
    }'
  ```
</CodeGroup>

<Tip>
  The response includes `usage.credits_used` so you can track your consumption in real-time.
</Tip>

## Step 4: Try Mave Agent (Optional)

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

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

  ```bash cURL theme={"dark"}
  curl -X POST https://app.mavera.io/api/v1/mave/chat \
    -H "Authorization: Bearer mvra_live_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "message": "Analyze the competitive landscape for electric vehicles in Europe"
    }'
  ```
</CodeGroup>

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:

<CardGroup cols={2}>
  <Card title="Quickstart: Chat" icon="comments" href="/quickstart-chat">
    Persona-powered responses in 5 minutes (Python, JavaScript, cURL)
  </Card>

  <Card title="Quickstart: Mave Agent" icon="brain" href="/quickstart-mave">
    First research query with sources and thread follow-ups
  </Card>

  <Card title="Quickstart: Focus Groups" icon="users" href="/quickstart-focus-groups">
    Create and run a synthetic focus group with NPS and Likert
  </Card>

  <Card title="Quickstart: Video Analysis" icon="video" href="/quickstart-video">
    Upload a video and get emotional and engagement metrics
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/guides/authentication">
    Learn about API key security and best practices
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/guides/rate-limits">
    Understand rate limiting and how to handle it
  </Card>

  <Card title="Responses API" icon="comments" href="/features/responses">
    Deep dive into the Responses API with personas
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore all available endpoints
  </Card>
</CardGroup>

## SDK Compatibility

Mavera's Responses API is compatible with OpenAI SDKs. Just change the base URL and use `client.responses.create()`:

| Language   | SDK         | Base URL Override                           |
| ---------- | ----------- | ------------------------------------------- |
| Python     | `openai`    | `base_url="https://app.mavera.io/api/v1"`   |
| JavaScript | `openai`    | `baseURL: "https://app.mavera.io/api/v1"`   |
| Go         | `go-openai` | Set `BaseURL` in config                     |
| Any        | REST        | Use `https://app.mavera.io/api/v1` directly |

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