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

# Introduction

> AI-powered marketing intelligence and customer research API

## Welcome to Mavera

Mavera provides AI-powered APIs for marketing intelligence, customer research, and content generation. Our APIs deliver real-time customer insights, persona-driven AI responses, and comprehensive market analysis.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get your first API call working in under 5 minutes
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore all endpoints with interactive examples
  </Card>

  <Card title="Authentication" icon="key" href="/guides/authentication">
    Learn how to authenticate your requests
  </Card>

  <Card title="Get API Key" icon="plus" href="https://app.mavera.io/settings/developer">
    Create your API key in the dashboard
  </Card>
</CardGroup>

### Quick starts by feature

Step-by-step guides for each major API with full code samples:

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

  <Card title="Quickstart: Mave Agent" icon="brain" href="/quickstart-mave">
    Research with sources, threads, and follow-ups
  </Card>

  <Card title="Quickstart: Focus Groups" icon="users" href="/quickstart-focus-groups">
    Run a synthetic focus group with multiple question types
  </Card>

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

### Tutorials

End-to-end integrations with external APIs. Each tutorial has full code (Python + JavaScript):

<CardGroup cols={2}>
  <Card title="Tutorials" icon="graduation-cap" href="/tutorials">
    Overview of all tutorials by API
  </Card>

  <Card title="Salesforce + Mavera" icon="cloud" href="/tutorials/salesforce-lead-scoring">
    Lead scoring with B2B persona → push narrative to CRM
  </Card>

  <Card title="HubSpot + Mavera" icon="envelope-open" href="/tutorials/hubspot-email-sequence">
    Email sequence scoring before you send
  </Card>

  <Card title="Zendesk + Mavera" icon="headset" href="/tutorials/zendesk-reply-draft">
    Ticket reply drafts with empathetic persona
  </Card>

  <Card title="Slack + Mavera" icon="comment" href="/tutorials/slack-tone-check">
    Message tone check before posting
  </Card>

  <Card title="Mixpanel + Mavera" icon="chart-line" href="/tutorials/mixpanel-funnel-insight">
    Funnel drop-off hypotheses
  </Card>

  <Card title="Stripe + Mavera" icon="credit-card" href="/tutorials/stripe-dunning-validation">
    Dunning message validation
  </Card>

  <Card title="Notion + Mavera" icon="table" href="/tutorials/notion-readability">
    Page readability scoring
  </Card>

  <Card title="GitHub + Mavera" icon="code" href="/tutorials/github-pr-review">
    PR description review
  </Card>
</CardGroup>

### Cookbooks

Production-ready patterns for common integration needs:

<CardGroup cols={2}>
  <Card title="Persona Selection" icon="user" href="/cookbooks/persona-selection">
    Use-case → persona matrix and programmatic selection
  </Card>

  <Card title="Migrate OpenAI → Mavera" icon="plug" href="/cookbooks/migrate-openai-to-mavera">
    Base URL and persona\_id with minimal code changes
  </Card>

  <Card title="Error Handling" icon="exclamation-triangle" href="/cookbooks/error-handling-patterns">
    Retries, backoff, user-facing messages, structured logging
  </Card>

  <Card title="Rate Limits in Production" icon="gauge" href="/cookbooks/rate-limits-production">
    Throttling, token bucket, concurrency limits, queuing
  </Card>

  <Card title="Credits & Budget Alerts" icon="coins" href="/cookbooks/credits-budget-alerts">
    Usage tracking, pre-flight checks, graceful degradation
  </Card>

  <Card title="Streaming Chat in React" icon="stream" href="/cookbooks/streaming-chat-react">
    React component and hook for Mavera streaming
  </Card>

  <Card title="Practical Workflow Ideas" icon="lightbulb" href="/guides/practical-workflow-ideas">
    200+ workflows: content, personas, Salesforce, HubSpot, Slack
  </Card>
</CardGroup>

## Core APIs

<CardGroup cols={2}>
  <Card title="Responses API" icon="comments" href="/features/responses">
    OpenAI-compatible Responses API with persona intelligence. Use any OpenAI SDK with Mavera personas for specialized, audience-aware responses.
  </Card>

  <Card title="Mave Agent" icon="brain" href="/features/mave-agent">
    AI research agent that conducts comprehensive investigations using multiple data sources, personas, and built-in fact-checking.
  </Card>

  <Card title="Focus Groups" icon="users" href="/features/focus-groups">
    AI-powered synthetic focus group research with customizable personas and 12 question types including NPS, Likert scales, and open-ended.
  </Card>

  <Card title="Video Analysis" icon="video" href="/features/video-analysis">
    Comprehensive video and advertisement analysis with emotional, cognitive, and behavioral metrics.
  </Card>
</CardGroup>

## Why Mavera?

<Steps>
  <Step title="Persona Intelligence">
    Every API call can be enhanced with specialized personas that inject domain expertise into AI responses. Choose from 50+ pre-built personas or create custom ones tailored to your target audience.
  </Step>

  <Step title="OpenAI SDK Compatible">
    Our Responses API is fully compatible with OpenAI SDKs. Just change the base URL, call `client.responses.create()`, and add a `persona_id` to supercharge your AI responses with audience insights.
  </Step>

  <Step title="Comprehensive Research">
    Mave agent conducts multi-phase research (Triage → Planning → Research → Execution → Validation) with built-in fact-checking and source attribution.
  </Step>

  <Step title="Credit-Based Pricing">
    Pay only for what you use. Every API response includes `credits_used` so you can track costs in real-time with full transparency.
  </Step>
</Steps>

## Quick Example

<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="How do millennials feel about remote work?",
      extra_body={"persona_id": "YOUR_PERSONA_ID"},
  )

  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: "How do millennials feel about remote work?",
    // @ts-ignore - Mavera custom field
    persona_id: "YOUR_PERSONA_ID",
  });

  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": "YOUR_PERSONA_ID",
      "input": "How do millennials feel about remote work?"
    }'
  ```
</CodeGroup>

## Base URL

All API requests should be made to:

```
https://app.mavera.io/api/v1
```

## Need Help?

<CardGroup cols={2}>
  <Card title="Support" icon="envelope" href="mailto:support@mavera.io">
    Contact our support team for assistance
  </Card>

  <Card title="API Status" icon="signal" href="https://status.mavera.io">
    Check real-time API status and incidents
  </Card>
</CardGroup>