> ## 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: Mave Agent > Run your first Mave research query with sources, threads, and follow-up questions in under 10 minutes ## What You'll Learn In this quickstart you will: * **Understand** how Mave differs from simple chat: a 5-phase research process with multiple data sources and fact-checking. * **Send your first message** to Mave and receive a researched response with **sources** and a **thread ID**. * **Continue the conversation** in the same thread for follow-up questions without repeating context. * **Inspect** validation (confidence, hallucination risk) and credit usage. * **Optionally** list and manage threads via the API. Mave is best for questions that benefit from live data (web, news, SEO) and cited answers—e.g. market analysis, competitive landscape, or trend research. **Time:** About 10 minutes (first response can take 30–90 seconds). **Credits:** A typical Mave query uses 10–50 credits depending on complexity. *** ## Prerequisites **Mavera account** with an active subscription and sufficient credits. Check usage at [app.mavera.io/settings/usage](https://app.mavera.io/settings/usage). **API key** from [Developer Settings](https://app.mavera.io/settings/developer). Keys start with `mvra_live_`. **HTTP client:** Python `requests`/`httpx`, Node `fetch`, or cURL. Mave is a REST endpoint (`POST /mave/chat`), not the OpenAI SDK. You'll use your language's HTTP client; the Responses API quickstart is optional background. *** ## How Mave Works (5 Phases) Mave doesn't just reply—it **researches** your question before answering: Classifies your query (Simple, Moderate, Complex, or Strategic) and decides whether to ask for clarification. Chooses which personas and data sources to use (web search, news, SEO, knowledge base) and plans the research steps. Runs tool calls in parallel to gather information from those sources. Writes a response that weaves together research and persona perspectives and cites sources. Performs a reality check, flags unsupported claims, and returns a confidence score and hallucination risk. You send a single `message` (and optionally a `thread_id` for follow-ups); Mave handles the rest and returns `content`, `sources`, `validation`, and `usage.credits_used`. *** ## Step 1: Send Your First Message Send a clear, specific question. Broad or vague questions still work but tend to produce broader answers and use more credits. ```python Python theme={"dark"} import requests API_KEY = "mvra_live_your_key_here" HEADERS = {"Authorization": f"Bearer {API_KEY}"} URL = "https://app.mavera.io/api/v1/mave/chat" response = requests.post( URL, headers=HEADERS, json={ "message": "What are the main factors driving electric vehicle adoption in Europe in 2024?" }, ) result = response.json() # Always check for API errors if "error" in result: raise Exception(result["error"]["message"]) print("Thread ID:", result["thread_id"]) print("Response preview:", result["content"][:300] + "..." if len(result["content"]) > 300 else result["content"]) print("Sources count:", len(result["sources"])) print("Credits used:", result["usage"]["credits_used"]) ``` ```javascript JavaScript theme={"dark"} const API_KEY = "mvra_live_your_key_here"; const URL = "https://app.mavera.io/api/v1/mave/chat"; const response = await fetch(URL, { method: "POST", headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ message: "What are the main factors driving electric vehicle adoption in Europe in 2024?", }), }); const result = await response.json(); if (result.error) { throw new Error(result.error.message); } console.log("Thread ID:", result.thread_id); console.log("Response preview:", result.content.slice(0, 300) + (result.content.length > 300 ? "..." : "")); console.log("Sources count:", result.sources.length); console.log("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": "What are the main factors driving electric vehicle adoption in Europe in 2024?" }' ``` Save the returned **`thread_id`** (e.g. `mave_thread_abc123`). You'll use it for follow-up questions so Mave keeps context. The first response can take **30–90 seconds** while Mave runs research. Use streaming (see below) or a loading state in production so users know the request is in progress. *** ## Step 2: Understand the Response Shape A successful Mave response looks like this (conceptually): | Field | Description | | -------------------- | ---------------------------------------------------------------------- | | `thread_id` | Use this in the next request to continue the conversation. | | `message_id` | Unique ID for this assistant message. | | `content` | Full markdown response with analysis and citations. | | `sources` | Array of objects with `title`, `url`, `snippet` (and possibly more). | | `personas_used` | Personas Mave used for the answer (id + name). | | `validation` | `passed`, `confidence_score`, `hallucination_risk` for quality checks. | | `usage.credits_used` | Credits consumed by this request. | Example (simplified): ```json theme={"dark"} { "thread_id": "mave_thread_abc123", "message_id": "msg_xyz789", "content": "## Electric Vehicle Adoption in Europe (2024)\n\nSeveral factors are driving adoption...", "sources": [ { "title": "European EV Sales Report 2024", "url": "https://example.com/report", "snippet": "EV adoption in Europe grew 25% year-over-year..." } ], "personas_used": [{ "id": "persona_123", "name": "Industry Analyst" }], "validation": { "passed": true, "confidence_score": 0.89, "hallucination_risk": "low" }, "usage": { "credits_used": 35 } } ``` Use `sources` to link users to evidence; use `validation` to decide how much to trust the answer (e.g. show a warning when `hallucination_risk` is not low). *** ## Step 3: Ask a Follow-Up in the Same Thread Send a second request with the **same `thread_id`** so Mave has full context and doesn't re-research from scratch. ```python Python theme={"dark"} # Assume you have thread_id from the first response thread_id = result["thread_id"] follow_up = requests.post( URL, headers=HEADERS, json={ "message": "What about Tesla's market share in Germany specifically?", "thread_id": thread_id, }, ) follow_up_result = follow_up.json() if "error" in follow_up_result: raise Exception(follow_up_result["error"]["message"]) print(follow_up_result["content"]) print("Credits this turn:", follow_up_result["usage"]["credits_used"]) ``` ```javascript JavaScript theme={"dark"} const threadId = result.thread_id; const followUp = await fetch(URL, { method: "POST", headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ message: "What about Tesla's market share in Germany specifically?", thread_id: threadId, }), }); const followUpResult = await followUp.json(); if (followUpResult.error) throw new Error(followUpResult.error.message); console.log(followUpResult.content); console.log("Credits this turn:", followUpResult.usage.credits_used); ``` ```bash cURL theme={"dark"} # Replace mave_thread_abc123 with your thread_id 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": "What about Tesla'\''s market share in Germany specifically?", "thread_id": "mave_thread_abc123" }' ``` Follow-ups in the same thread are typically faster and use fewer credits than starting a new thread, because Mave reuses prior research where relevant. *** ## Step 4: Optional — Enable Streaming For long answers, you can stream content as it's generated so users see progress immediately. ```python Python theme={"dark"} import httpx import json with httpx.stream( "POST", URL, headers=HEADERS, json={ "message": "Summarize the latest trends in renewable energy in Europe.", "stream": True, }, timeout=120.0, ) as response: for line in response.iter_lines(): if line.startswith("data: "): payload = line[6:].strip() if payload == "[DONE]": break try: data = json.loads(payload) if data.get("type") == "content" and data.get("content"): print(data["content"], end="", flush=True) except json.JSONDecodeError: pass print() ``` ```javascript JavaScript theme={"dark"} const streamResponse = await fetch(URL, { method: "POST", headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ message: "Summarize the latest trends in renewable energy in Europe.", stream: true, }), }); const reader = streamResponse.body.getReader(); const decoder = new TextDecoder(); let buffer = ""; while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const lines = buffer.split("\n"); buffer = lines.pop() || ""; for (const line of lines) { if (line.startsWith("data: ")) { const payload = line.slice(6).trim(); if (payload === "[DONE]") break; try { const data = JSON.parse(payload); if (data.type === "content" && data.content) { process.stdout.write(data.content); } } catch (_) {} } } } console.log(); ``` Streaming responses may still include a final non-streamed payload with `thread_id`, `sources`, and `usage`; check the API reference or the actual response format for your version. *** ## Step 5: List and Manage Threads You can list your threads, fetch one thread's details, or delete a thread when you're done. ```python Python theme={"dark"} # List threads list_resp = requests.get( "https://app.mavera.io/api/v1/mave/threads", headers=HEADERS, ) threads = list_resp.json() print(threads) # Structure may include data[], next_cursor, etc. # Get one thread thread_resp = requests.get( f"https://app.mavera.io/api/v1/mave/threads/{thread_id}", headers=HEADERS, ) thread_detail = thread_resp.json() # Delete a thread del_resp = requests.delete( f"https://app.mavera.io/api/v1/mave/threads/{thread_id}", headers=HEADERS, ) ``` ```bash cURL theme={"dark"} # List threads curl -s https://app.mavera.io/api/v1/mave/threads \ -H "Authorization: Bearer mvra_live_your_key_here" # Get thread curl -s "https://app.mavera.io/api/v1/mave/threads/mave_thread_abc123" \ -H "Authorization: Bearer mvra_live_your_key_here" # Delete thread curl -X DELETE "https://app.mavera.io/api/v1/mave/threads/mave_thread_abc123" \ -H "Authorization: Bearer mvra_live_your_key_here" ``` Deleting a thread is irreversible; the conversation history for that thread is no longer available. *** ## Credit Expectations Mave is more expensive than simple chat because it runs multiple phases and data sources: | Query type | Typical credits | | ------------------- | --------------- | | Simple question | 10–15 | | Moderate research | 20–30 | | Complex analysis | 30–50 | | Strategic deep-dive | 40–75 | Monitor `usage.credits_used` and set [budget alerts](https://app.mavera.io/settings/usage) or use [Credits](/guides/credits) best practices so you don't run out mid-session. *** ## Common Issues Mave research can take 30–90 seconds. Increase your HTTP client timeout (e.g. 120 seconds) or use streaming so the connection stays active while content is generated. The thread may have been deleted or the ID might be from another account/workspace. Start a new conversation by omitting `thread_id` in the next request. Your account has no credits left. Refill credits or enable auto-recharge; see [Credits](/guides/credits). Mave has stricter concurrency limits. Space out requests or implement retries with backoff; see [Rate Limits](/guides/rate-limits) and [Errors](/guides/errors). *** ## Next Steps Data sources, validation, and best practices Simpler, cheaper persona-driven responses when you don't need research Allocation, costs by endpoint, and budget alerts Full Mave chat and thread API specification Use Mave when you need **cited, multi-source research**. Use the [Responses API](/quickstart-chat) when you need **fast, persona-based conversation** without live data.