> ## 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. # List available personas > Returns all personas accessible to the authenticated user. This includes base/global personas (available to everyone) and custom personas created within the user's workspaces. The `prompt` field is excluded from responses for IP protection. Use the returned `id` as the `persona_id` parameter in chat completions to inject persona intelligence into conversations. ## OpenAPI ````yaml /openapi.json get /personas 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: /personas: get: tags: - Personas summary: List available personas description: >- Returns all personas accessible to the authenticated user. This includes base/global personas (available to everyone) and custom personas created within the user's workspaces. The `prompt` field is excluded from responses for IP protection. Use the returned `id` as the `persona_id` parameter in chat completions to inject persona intelligence into conversations. operationId: listPersonas parameters: - name: is_custom in: query description: Filter by custom personas only schema: type: boolean - name: category in: query description: Filter by category schema: type: string - name: search in: query description: Search by name or description schema: type: string - name: limit in: query description: Maximum number of results (default 50, max 100) schema: type: integer minimum: 1 maximum: 100 default: 50 - name: cursor in: query description: Cursor for pagination schema: type: string responses: '200': description: A list of personas accessible to the authenticated user. content: application/json: schema: $ref: '#/components/schemas/PersonaListResponse' example: object: list data: - id: clx1abc2d0001abcdef123456 object: persona name: Gen Z Consumer category: Generational description: >- Digital-native consumer aged 18-25 with strong social media influence. is_custom: false is_expert: false created_at: 1706140800 - id: clx2xyz9e0002abcdef789012 object: persona name: SaaS CMO category: IndustrySpecific description: >- Chief Marketing Officer at a B2B SaaS company with $10M+ ARR. is_custom: true is_expert: true created_at: 1706227200 '401': description: Authentication error — missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: Invalid API key. type: authentication_error code: invalid_api_key param: null '429': description: Rate limit exceeded. 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. 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 https://app.mavera.io/api/v1/personas \ -H "Authorization: Bearer mvra_live_your_key_here" - lang: python label: Python source: |- 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 p in personas: print(f"{p['name']} ({p['category']}) - {p['description']}") - lang: javascript label: JavaScript source: >- 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.forEach((p) => console.log(`${p.name} (${p.category})`)); - lang: python label: Python (Chat with Persona) source: |- from openai import OpenAI import requests # 1. List personas headers = {"Authorization": "Bearer mvra_live_your_key_here"} personas = requests.get( "https://app.mavera.io/api/v1/personas", headers=headers, ).json()["data"] # 2. Pick a persona and use it in chat persona_id = personas[0]["id"] client = OpenAI( api_key="mvra_live_your_key_here", base_url="https://app.mavera.io/api/v1", ) response = client.chat.completions.create( model="mavera-1", messages=[{"role": "user", "content": "Analyze this market trend."}], extra_body={"persona_id": persona_id}, ) print(response.choices[0].message.content) components: schemas: PersonaListResponse: type: object properties: object: type: string enum: - list description: The object type, always `list`. example: list data: type: array description: The list of personas. items: $ref: '#/components/schemas/Persona' has_more: type: boolean description: Whether there are more results available. next_cursor: type: string nullable: true description: Cursor to use for fetching the next page. example: object: list data: - id: clx1abc2d0001abcdef123456 object: persona name: Gen Z Consumer category: Generational description: >- Digital-native consumer aged 18-25 with strong social media influence. is_custom: false is_expert: false created_at: 1706140800 has_more: false 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 Persona: type: object properties: id: type: string description: Unique identifier for the persona (CUID). example: clx1abc2d0001abcdef123456 object: type: string enum: - persona description: The object type, always `persona`. example: persona name: type: string description: Human-readable name of the persona. example: Gen Z Consumer category: type: string enum: - Generational - Demographic - Psychographic - Behavioral - IndustrySpecific - Mentor - Finance description: The category this persona belongs to. example: Generational description: type: string description: A brief description of the persona's characteristics. example: >- Digital-native consumer aged 18-25 with strong social media influence. is_custom: type: boolean description: Whether this is a custom persona created by the user. example: false is_expert: type: boolean description: Whether this persona has expert-level knowledge. example: false created_at: type: integer description: Unix timestamp (in seconds) of when the persona was created. example: 1706140800 securitySchemes: BearerAuth: type: http scheme: bearer description: >- API key prefixed with `mvra_live_`. Create keys at **Settings > Developer > API Keys**. ````