> ## 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. # Create a response > Generates a model response for the given input. Supports both non-streaming and SSE streaming responses via the OpenAI Responses API format. Inject a Mavera persona via `persona_id` to prepend a curated system prompt. When `stream: true`, the response is a series of named `text/event-stream` Server-Sent Events (e.g. `response.created`, `response.output_text.delta`, `response.completed`). The stream ends with `data: [DONE]`. ## OpenAPI ````yaml /openapi.json post /responses openapi: 3.0.3 info: title: Mavera API version: 1.0.0 description: >- # Getting Started The Mavera Responses API provides persona-powered AI responses using the **OpenAI Responses API format**. Use `client.responses.create()` with the OpenAI SDK — just set the base URL to `https://app.mavera.io/api/v1`. ## Authentication All API requests require a Bearer token. Create an API key in **Settings > Developer > API Keys**. ``` Authorization: Bearer mvra_live_your_key_here ``` ## Quick Start ### Step 1: Get a Persona ID Every response request requires a `persona_id`. First, list available personas: ```bash curl https://app.mavera.io/api/v1/personas \ -H "Authorization: Bearer mvra_live_your_key_here" ``` This returns personas you can use. Copy the `id` field from any persona. ### Step 2: Create a Response Use the persona ID in your request: ```bash curl 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": "Hello!" }' ``` ## Rate Limits Per-key sliding window limits based on your subscription tier: | Tier | Requests / min | |------|---------------| | Starter | 60 | | Basic | 120 | | Professional | 240 | | Enterprise | 600 | When rate limited, the response includes a `Retry-After` header indicating how many seconds to wait. ## Credits Each API call consumes credits from your subscription. The `usage.credits_used` field in the response shows the cost of each request. contact: name: Mavera Support url: https://mavera.io x-logo: url: /Mavera_Logo_Full.png altText: Mavera servers: - url: https://app.mavera.io/api/v1 description: Production - url: https://dev.mavera.io/api/v1 description: Development security: - BearerAuth: [] tags: - name: System description: Health checks and operational status. - name: Responses description: >- Generate persona-powered AI responses using the OpenAI Responses API format. Use `client.responses.create()` with the OpenAI SDK. - name: Models description: Discover available models and their capabilities. - name: Personas description: >- Browse available personas to inject specialized intelligence into responses via `persona_id`. - name: Custom Personas description: >- Create, manage, and customize AI-powered personas. Supports three creation pipelines: North Star (AI-generated from minimal input), Intermediate (guided 3-step process), and Advanced (full B2B/B2C customization with psychographics and purpose packs). 300 credits per persona. - name: Brand Voice description: >- Create, manage, and retrieve brand voice profiles for AI-powered content generation. Upload URLs and documents to analyze, and the AI will generate tone guidelines, vocabulary preferences, and writing style recommendations. - name: Generations description: >- Generate AI-powered content using pre-built templates with optional brand voice styling. Browse available generation apps, create content, and manage your generation history. Supports streaming responses. - name: Mave description: >- Mave is Mavera's AI-powered research and analysis agent. Send messages to conduct comprehensive investigations using multiple data sources, personas, and fact-checking. Mave uses a multi-phase orchestration process (Triage, Planning, Research, Execution, Validation) to deliver well-researched responses with sources. - name: Workspaces description: >- Manage workspaces for organizing your work. Workspaces contain projects, threads, personas, and other resources. Invite team members with role-based access control. Set budget alerts and usage limits. - name: Projects description: >- Organize work within workspaces using projects. Projects contain threads, generations, and other resources. Track usage and set per-project budget controls. - name: Meetings description: >- Access meeting recordings, transcripts, and AI-powered analysis. List meetings, retrieve transcripts in multiple formats (segments, text, SRT), get AI analysis with summaries, tasks, decisions, highlights, and coaching metrics. Run custom schemas to extract structured data from transcripts. - name: Schemas description: >- Create and manage meeting schemas for structured data extraction. Schemas define fields to extract from meeting transcripts, with support for various field types (text, enum, list, boolean, etc.), evidence tracking, and scoring. - name: Files description: >- Upload, manage, and retrieve files/assets. Use presigned URLs for direct uploads to avoid passing files through the API. Supports images, videos, documents, and more. File uploads count against your storage quota. - name: Folders description: >- Create and manage folders to organize your files. Folders can be favorited and shared with workspace members. - name: Video Analysis description: >- AI-powered video and advertisement analysis. Submit videos for comprehensive emotional, cognitive, behavioral, and technical analysis. Chat with AI about the results. - name: Focus Groups description: >- AI-powered synthetic focus group research. Create focus groups with personas to gather market research, product feedback, and audience insights. Supports 12 question types including NPS, Likert scales, and open-ended responses. - name: News description: >- AI-powered news intelligence. Browse trending stories, get AI analysis from persona perspectives, and manage scheduled news digests. Story analysis uses credits based on token usage. - name: Usage description: >- Monitor your subscription usage including credits, transcription minutes, storage, and API request metrics. Get real-time statistics on your billing period usage. paths: /responses: post: tags: - Responses summary: Create a response description: >- Generates a model response for the given input. Supports both non-streaming and SSE streaming responses via the OpenAI Responses API format. Inject a Mavera persona via `persona_id` to prepend a curated system prompt. When `stream: true`, the response is a series of named `text/event-stream` Server-Sent Events (e.g. `response.created`, `response.output_text.delta`, `response.completed`). The stream ends with `data: [DONE]`. operationId: createResponse requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ResponseRequest' example: model: mavera-1 persona_id: clx1abc2d0001abcdef123456 input: Explain quantum computing in simple terms. responses: '200': description: >- Successful response. Returns a response object with the model-generated output and credit cost. content: application/json: schema: $ref: '#/components/schemas/ResponseObject' example: id: resp_abc123def456abc123def456 object: response created_at: 1706345678 status: completed model: mavera-1 output: - id: msg_abc123def456 type: message role: assistant status: completed content: - type: output_text text: >- Quantum computing uses quantum bits (qubits) that can exist in multiple states simultaneously, unlike classical bits that are either 0 or 1. This allows quantum computers to process many possibilities at once. usage: input_tokens: 42 output_tokens: 68 total_tokens: 110 credits_used: 3 text/event-stream: schema: type: string description: >- SSE stream of named Responses API events. Each event has an `event:` line followed by `data:` JSON. Key events: `response.created`, `response.output_item.added`, `response.output_text.delta`, `response.output_text.done`, `response.output_item.done`, `response.completed`. Stream ends with `data: [DONE]`. '400': description: >- Invalid request — missing required fields, invalid model, or malformed input. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: >- Model 'unknown-model' is not supported. Use GET /api/v1/models to see available models. type: invalid_request_error code: invalid_model param: model '401': description: Authentication error — missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: >- Invalid API key. Ensure your key starts with 'mvra_live_' and has not been revoked. type: authentication_error code: invalid_api_key param: null '402': description: Insufficient credits — your subscription has run out of credits. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: >- Insufficient credits. Please upgrade your subscription or wait for your next billing cycle. type: insufficient_credits code: credits_exhausted param: null '429': description: Rate limit exceeded. Check the `Retry-After` header. headers: Retry-After: schema: type: integer example: 30 description: Seconds to wait before retrying content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: Rate limit exceeded. Please retry after 30 seconds. type: rate_limit_error code: rate_limit_exceeded param: null '500': description: Internal server error — an unexpected error occurred on our side. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: An internal error occurred. Please try again later. type: api_error code: internal_error param: null x-codeSamples: - lang: curl label: cURL source: |- 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": "Explain quantum computing in simple terms." }' - lang: python label: Python source: |- 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="Explain quantum computing in simple terms.", extra_body={"persona_id": "YOUR_PERSONA_ID"}, ) # Access the text output print(response.output[0].content[0].text) print(f"Credits used: {response.usage.credits_used}") - lang: javascript label: JavaScript source: |- 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: "Explain quantum computing in simple terms.", // @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); - lang: curl label: cURL (Streaming) source: |- 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": "Write a haiku about AI.", "stream": true }' - lang: python label: Python (Streaming) source: |- from openai import OpenAI client = OpenAI( api_key="mvra_live_your_key_here", base_url="https://app.mavera.io/api/v1", ) with client.responses.stream( model="mavera-1", input="Write a haiku about AI.", extra_body={"persona_id": "YOUR_PERSONA_ID"}, ) as stream: for event in stream: if event.type == "response.output_text.delta": print(event.delta, end="", flush=True) - lang: curl label: cURL (With Image) source: |- 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": [ { "role": "user", "content": [ { "type": "input_text", "text": "What is in this image?" }, { "type": "input_image", "image_url": "https://your-bucket.s3.amazonaws.com/image.png" } ] } ] }' - lang: python label: Python (Analysis Mode) source: >- 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", "analysis_mode": True, }, ) print(response.output[0].content[0].text) analysis = response.analysis print(f"Confidence: {analysis['confidence']}/10") print(f"Emotional valence: {analysis['emotion']['emotional_valence']}/10") print(f"Biases: {[b['name'] for b in analysis['biases']]}") - lang: python label: Python (Structured Output) source: |- from openai import OpenAI import json 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="Review this product: Great quality, fast shipping!", extra_body={ "persona_id": "YOUR_PERSONA_ID", "text": { "format": { "type": "json_schema", "json_schema": { "name": "product_review", "strict": True, "schema": { "type": "object", "properties": { "sentiment": {"type": "string", "enum": ["positive", "neutral", "negative"]}, "score": {"type": "number"}, "summary": {"type": "string"} }, "required": ["sentiment", "score", "summary"] } } } } }, ) data = response.parsed # Already parsed for you print(f"Sentiment: {data['sentiment']}, Score: {data['score']}/10") - lang: python label: Python (Tool Calling) source: |- from openai import OpenAI client = OpenAI( api_key="mvra_live_your_key_here", base_url="https://app.mavera.io/api/v1", ) tools = [ { "type": "function", "name": "get_weather", "description": "Get the weather for a city", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "City name"} }, "required": ["city"] } } ] response = client.responses.create( model="mavera-1", input="What's the weather in New York?", tools=tools, extra_body={"persona_id": "YOUR_PERSONA_ID"}, ) # Check for function calls in output for item in response.output: if item.type == "function_call": print(f"Tool: {item.name}, Args: {item.arguments}") # Execute the tool and send results back result = get_weather(item.name, item.arguments) follow_up = client.responses.create( model="mavera-1", input=[ *response.output, { "type": "function_call_output", "call_id": item.call_id, "output": str(result) } ], tools=tools, extra_body={"persona_id": "YOUR_PERSONA_ID"}, ) print(follow_up.output[0].content[0].text) components: schemas: ResponseRequest: type: object required: - model - input - persona_id properties: model: type: string description: Model ID to use for the response. enum: - mavera-1 example: mavera-1 input: description: >- The input to the model. Can be a simple string for single-turn requests, or an array of input items for multi-turn conversations with tool calls. oneOf: - type: string description: A simple text prompt. maxLength: 100000 example: Explain quantum computing in simple terms. - type: array description: >- An array of input items representing a conversation. Items can be messages, function call replay, or function call outputs. minItems: 1 maxItems: 128 items: oneOf: - type: object description: A conversation message. required: - role - content properties: type: type: string enum: - message description: Optional item type (defaults to 'message'). role: type: string enum: - system - user - assistant description: The role of the message author. example: user content: description: >- The content of the message. Can be a string or an array of content parts. oneOf: - type: string maxLength: 100000 description: Plain text content. example: What's in this image? - type: array description: Multimodal content parts. items: oneOf: - type: object required: - type - text properties: type: type: string enum: - input_text - text text: type: string description: The text content. - type: object required: - type - image_url properties: type: type: string enum: - input_image image_url: type: string format: uri description: >- URL of the image. Must be publicly accessible. example: >- https://your-bucket.s3.amazonaws.com/image.png detail: type: string enum: - high - low - auto default: auto attachments: type: array description: >- Mavera extension: optional array of image or document attachments. maxItems: 10 items: type: object required: - type - url properties: type: type: string enum: - image - document example: image url: type: string format: uri example: https://your-bucket.s3.amazonaws.com/image.png - type: object description: >- A function call item — used when replaying a prior response that contained function calls. required: - type - call_id - name - arguments properties: type: type: string enum: - function_call call_id: type: string description: >- The call ID from the prior response's function_call output item. example: call_abc123 name: type: string description: The function name. example: get_weather arguments: type: string description: JSON-encoded function arguments. example: '{"city":"New York"}' - type: object description: >- A function call output — the result of executing a function call. required: - type - call_id - output properties: type: type: string enum: - function_call_output call_id: type: string description: The call_id from the corresponding function_call item. example: call_abc123 output: type: string description: The result of the function call as a string. example: 72°F, sunny example: Explain quantum computing in simple terms. persona_id: type: string description: >- **Required.** A Mavera persona CUID. The persona's curated system prompt is prepended to the conversation. Use `GET /api/v1/personas` to list available personas. example: clx1abc2d0001abcdef123456 instructions: type: string description: >- Optional system-level instructions to guide the model's behavior. Appended to the persona system prompt. example: Always respond in bullet points. stream: type: boolean default: false description: >- If `true`, responses are streamed as named Server-Sent Events (SSE). The stream ends with `data: [DONE]`. example: false text: type: object description: >- Output format configuration. Replaces the legacy `response_format` field. properties: format: type: object required: - type description: Specify how the model should format its output. properties: type: type: string enum: - text - json_object - json_schema description: >- `text` returns plain text (default). `json_object` returns valid JSON. `json_schema` returns JSON matching your schema. json_schema: type: object description: Required when type is `json_schema`. required: - name - schema properties: name: type: string description: Schema identifier. description: type: string schema: type: object description: A valid JSON Schema object. strict: type: boolean default: true example: type: json_schema json_schema: name: product_review strict: true schema: type: object properties: sentiment: type: string enum: - positive - neutral - negative score: type: number summary: type: string required: - sentiment - score - summary tools: type: array maxItems: 64 description: >- A list of tools (functions) the model may call. Uses the flat Responses API format — `name` and `parameters` are directly on the tool object. items: type: object required: - type - name properties: type: type: string enum: - function description: Always `function`. name: type: string description: The function name. Must match `[a-zA-Z_][a-zA-Z0-9_-]*`. example: get_weather description: type: string description: A description of what the function does. example: Get the current weather for a city parameters: type: object description: A JSON Schema object describing the function parameters. example: type: object properties: city: type: string description: The city name required: - city strict: type: boolean default: false description: If true, the model strictly adheres to the parameter schema. example: - type: function name: get_weather description: Get the current weather for a city parameters: type: object properties: city: type: string description: The city name required: - city tool_choice: description: >- Controls which tool is called. `auto` (default) lets the model decide, `none` disables tools, `required` forces tool use, or `{ type: 'function', name: 'fn' }` forces a specific function. oneOf: - type: string enum: - auto - none - required - type: object description: Force a specific function call. required: - type - name properties: type: type: string enum: - function name: type: string description: The function name to force. example: auto analysis_mode: type: boolean default: false description: >- If `true`, returns structured analysis including emotional metrics, biases, confidence scores, and news relevance. Cannot be used with `text.format`. example: false canvas_mode: type: boolean default: false description: >- If `true`, enables artifact generation mode. The AI will generate structured content wrapped in `` tags. example: false reasoning_effort: type: string enum: - low - medium - high default: medium description: >- Controls reasoning depth. `high` produces more thorough responses at the cost of latency. example: medium verbosity: type: string enum: - low - medium - high default: medium description: >- Controls response detail. `low` for concise, `high` for comprehensive. example: medium previous_response_id: type: string description: >- The ID of a prior response to continue. Currently accepted but has no effect — pass full conversation history via `input` instead. example: resp_abc123def456 store: type: boolean default: false description: Whether to store the response. Currently accepted but has no effect. example: model: mavera-1 persona_id: clx1abc2d0001abcdef123456 input: Explain quantum computing in simple terms. ResponseObject: type: object description: A completed response object. properties: id: type: string description: Unique response ID with `resp_` prefix. example: resp_abc123def456abc123def456 object: type: string enum: - response description: Always `response`. example: response created_at: type: integer description: Unix timestamp (seconds) when the response was created. example: 1706345678 status: type: string enum: - completed - in_progress - failed description: Response status. example: completed model: type: string description: The model used. example: mavera-1 output: type: array description: >- Ordered list of output items. Typically a single `message` item with text, or one or more `function_call` items when the model wants to call tools. items: oneOf: - type: object description: A message output item. properties: id: type: string example: msg_abc123def456 type: type: string enum: - message role: type: string enum: - assistant status: type: string enum: - completed - in_progress content: type: array description: Content parts of the message. items: type: object properties: type: type: string enum: - output_text text: type: string description: The generated text. - type: object description: >- A function call output item — the model wants you to execute this. properties: type: type: string enum: - function_call id: type: string example: fc_abc123def456 call_id: type: string description: >- Use this as `call_id` in your `function_call_output` input item. example: call_abc123 name: type: string example: get_weather arguments: type: string description: JSON-encoded function arguments. example: '{"city":"New York"}' usage: type: object description: Token and credit usage. properties: input_tokens: type: integer description: Tokens in the input. example: 42 output_tokens: type: integer description: Tokens in the output. example: 68 total_tokens: type: integer description: Total tokens. example: 110 credits_used: type: integer description: Credits consumed from your subscription. example: 3 server_tool_calls: type: array description: >- Mavera's built-in server-side tools automatically executed during this request. Only present when server tools were used. items: type: object properties: name: type: string example: tavily_search args: type: object example: query: latest AI news result: type: object analysis: type: object description: Structured analysis data. Present when `analysis_mode` is `true`. properties: response: type: string emotion: type: object properties: emotional_valence: type: number emotional_arousal: type: number explanation: type: string pragmatic: type: object properties: pragmatic_realism: type: number pragmatic_actionability: type: number explanation: type: string biases: type: array items: type: object properties: name: type: string description: type: string impact: type: number examples: type: array items: type: string suggested_mitigation: type: string confidence: type: number spread_of_opinions: type: number extreme_min_opinion: type: string extreme_max_opinion: type: string news_relevant: type: array items: type: object properties: story: type: string impact: type: number source: type: string source_url: type: string follow_up_questions: type: array items: type: string parsed: type: object description: >- Present when `text.format.type` is `json_schema`. Contains the parsed JSON object — a convenience field, same data is also in `output[0].content[0].text`. example: sentiment: positive score: 8.5 summary: Great product example: id: resp_abc123def456abc123def456 object: response created_at: 1706345678 status: completed model: mavera-1 output: - id: msg_abc123def456 type: message role: assistant status: completed content: - type: output_text text: >- Quantum computing uses qubits that can exist in multiple states simultaneously, enabling processing of many possibilities at once. usage: input_tokens: 42 output_tokens: 68 total_tokens: 110 credits_used: 3 ErrorResponse: type: object description: >- All error responses follow this format. The `type` field indicates the category of error, and `code` provides a machine-readable error code. properties: error: type: object properties: message: type: string description: A human-readable error message. example: Invalid API key. type: type: string enum: - invalid_request_error - authentication_error - insufficient_credits - not_found - rate_limit_error - api_error description: The category of error. example: authentication_error code: type: string description: A machine-readable error code. example: invalid_api_key param: type: string nullable: true description: The request parameter that caused the error, if applicable. example: null example: error: message: Invalid API key. type: authentication_error code: invalid_api_key param: null securitySchemes: BearerAuth: type: http scheme: bearer description: >- API key prefixed with `mvra_live_`. Create keys at **Settings > Developer > API Keys**. ````