Skip to main content

​
Installation

npm install openai
# or
yarn add openai
# or
pnpm add openai
Minimum: Node.js 18+ (for native fetch). The OpenAI SDK works with Mavera’s Responses API via baseURL override.

​
Install Troubleshooting

Install the official openai package. Avoid openai-api, openai-node, or similar. Verify with npm list openai.
The SDK supports both. Use "type": "module" in package.json for ESM, or require("openai") for CommonJS. For TypeScript, ensure moduleResolution is compatible.
The OpenAI types don’t include persona_id. Add it directly to the request object; use // @ts-expect-error above the line, or extend the types if needed.
Node 18+ required. Check with node -v. For older Node, consider upgrading or using the REST API directly.

​
Migrating from OpenAI

If you’re switching from OpenAI to Mavera, change only these:
  1. baseURL — baseURL: "https://app.mavera.io/api/v1"
  2. apiKey — Use your Mavera key (starts with mvra_live_)
  3. model — Use mavera-1
  4. persona_id — Add persona_id: "..." to every responses.create() call (JavaScript accepts it directly; no extra_body)
Streaming, tools, and structured outputs work with minor adjustments. See Migrate OpenAI to Mavera.

​
Configuration

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "mvra_live_your_key_here",
  baseURL: "https://app.mavera.io/api/v1",
});
Store your API key in an environment variable: MAVERA_API_KEY
const client = new OpenAI({
  apiKey: process.env.MAVERA_API_KEY,
  baseURL: "https://app.mavera.io/api/v1",
});

​
Responses API

​
Basic Usage

const response = await client.responses.create({
  model: "mavera-1",
  input: "What are the latest trends in AI?",
  instructions: "You are a helpful assistant.",
  // @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);

​
Streaming

const stream = client.responses.stream({
  model: "mavera-1",
  input: "Write a short story",
  // @ts-ignore - Mavera custom field
  persona_id: "YOUR_PERSONA_ID",
});

for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}

​
With Analysis Mode

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",
  analysis_mode: true,
  reasoning_effort: "high",
});

const analysis = response.analysis;
console.log(`Confidence: ${analysis.confidence}/10`);

​
REST API Endpoints

For non-Chat endpoints, use fetch: 
const headers = {
  Authorization: "Bearer mvra_live_your_key_here",
  "Content-Type": "application/json",
};
const baseURL = "https://app.mavera.io/api/v1";

// List personas
const personasRes = await fetch(`${baseURL}/personas`, { headers });
const { data: personas } = await personasRes.json();

// Mave Agent
const maveRes = await fetch(`${baseURL}/mave/chat`, {
  method: "POST",
  headers,
  body: JSON.stringify({ message: "Analyze the EV market" }),
});
const maveResult = await maveRes.json();

// Create Focus Group
const fgRes = await fetch(`${baseURL}/focus-groups`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Product Feedback",
    sample_size: 50,
    persona_ids: ["persona_1", "persona_2"],
    questions: [...],
  }),
});

​
TypeScript Support

The SDK includes full TypeScript types: 
import OpenAI from "openai";

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

const response = await client.responses.create({
  model: "mavera-1",
  input: "Hello",
  // @ts-ignore - Mavera custom field
  persona_id: "YOUR_PERSONA_ID",
});

​
Error Handling

import OpenAI from "openai";

try {
  const response = await client.responses.create({...});
} catch (error) {
  if (error instanceof OpenAI.AuthenticationError) {
    console.error("Invalid API key");
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("Rate limited - implement backoff");
  } else if (error instanceof OpenAI.APIError) {
    if (error.status === 402) {
      console.error("Insufficient credits");
    } else {
      console.error("API error:", error.message);
    }
  }
}

​
Edge Runtime / Vercel

Works in Edge Runtime environments: 
// app/api/chat/route.ts
import OpenAI from "openai";

export const runtime = "edge";

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

export async function POST(req: Request) {
  const { message } = await req.json();

  const response = await client.responses.create({
    model: "mavera-1",
    input: message,
    // @ts-ignore - Mavera custom field
    persona_id: process.env.PERSONA_ID,
  });

  return Response.json(response);
}

​
React / Next.js Example

"use client";

import { useState } from "react";

export function Chat() {
  const [message, setMessage] = useState("");
  const [response, setResponse] = useState("");

  const handleSubmit = async () => {
    const res = await fetch("/api/chat", {
      method: "POST",
      body: JSON.stringify({ message }),
    });
    const data = await res.json();
    setResponse(data.output[0].content[0].text);
  };

  return (
    <div>
      <input value={message} onChange={(e) => setMessage(e.target.value)} />
      <button onClick={handleSubmit}>Send</button>
      <p>{response}</p>
    </div>
  );
}

​
Full Example Script (Node.js)

A runnable script: list personas, send a chat, print the response. 
// mavera_chat.mjs — run with: node mavera_chat.mjs "Your question here"
import OpenAI from "openai";

const apiKey = process.env.MAVERA_API_KEY;
if (!apiKey) {
  console.error("Set MAVERA_API_KEY environment variable");
  process.exit(1);
}

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

async function main() {
  const question = process.argv[2] || "What matters most to you when choosing a product?";

  const personasRes = await fetch("https://app.mavera.io/api/v1/personas", {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  const { data: personas } = await personasRes.json();
  const personaId = personas?.[0]?.id;
  if (!personaId) {
    console.error("No personas found");
    process.exit(1);
  }
  console.log(`Using persona: ${personas[0].name}\n`);

  const response = await client.responses.create({
    model: "mavera-1",
    input: question,
    // @ts-ignore - Mavera custom field
    persona_id: personaId,
  });

  console.log(response.output[0].content[0].text);
  console.log(`\nCredits used: ${response.usage.credits_used}`);
}

main().catch(console.error);
Run: MAVERA_API_KEY=mvra_live_xxx node mavera_chat.mjs "How do you feel about subscription pricing?"

Quickstart: Chat

First chat in 5 minutes

Migrate OpenAI → Mavera

Switching from OpenAI

Streaming Chat in React

React component for streaming

API Reference

Responses API spec