> ## 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 custom persona > Create a custom AI-powered persona using one of three pipeline types: **North Star** (`north_star`): Quick AI-generated persona from minimal input. First call `/personas/suggestions` to get options, then create with the selected suggestion. **Intermediate** (`intermediate`): Guided persona with structured fields for goals, pains, channels, and market alignment. **Advanced** (`advanced`): Full-featured persona with B2B/B2C specifics, psychographics, and purpose packs. **Pricing**: 300 credits per persona created. ## OpenAPI ````yaml /openapi.json post /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: post: tags: - Custom Personas summary: Create a custom persona description: >- Create a custom AI-powered persona using one of three pipeline types: **North Star** (`north_star`): Quick AI-generated persona from minimal input. First call `/personas/suggestions` to get options, then create with the selected suggestion. **Intermediate** (`intermediate`): Guided persona with structured fields for goals, pains, channels, and market alignment. **Advanced** (`advanced`): Full-featured persona with B2B/B2C specifics, psychographics, and purpose packs. **Pricing**: 300 credits per persona created. operationId: createCustomPersona requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCustomPersonaRequest' responses: '201': description: Custom persona created successfully. content: application/json: schema: $ref: '#/components/schemas/CustomPersonaResponse' '400': description: Validation error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '402': description: Insufficient credits. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: curl label: cURL (Intermediate) source: |- curl -X POST https://app.mavera.io/api/v1/personas \ -H "Authorization: Bearer mvra_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "pipeline_type": "intermediate", "name": "Enterprise CMO", "type": "B2B", "role_segment": ["CMO", "VP Marketing"], "buying_stage": "SOLUTION_AWARE", "decision_role": "ECONOMIC_BUYER", "primary_objectives": ["Drive revenue growth", "Optimize marketing spend"], "mcda_weights": {"price": 3, "timeToValue": 4, "risk": 2, "proof": 5, "support": 3}, "goals": ["Increase marketing ROI", "Scale demand generation"], "pains": ["Attribution challenges", "Budget constraints", "Tech stack complexity"], "triggers": ["New fiscal year", "Board pressure", "Competitor threat"], "channels": ["LinkedIn", "Industry events", "Peer referrals"], "proof_types": ["Case studies", "ROI calculators", "Peer references"], "alternatives": ["HubSpot", "Marketo", "In-house solution"], "win_factors": ["Time to value", "Integration ease", "Support quality"], "objections": ["Implementation time", "Team adoption", "Data migration"] }' - lang: python label: Python (Advanced B2B) source: |- import requests headers = {"Authorization": "Bearer mvra_live_your_key_here"} response = requests.post( "https://app.mavera.io/api/v1/personas", headers=headers, json={ "pipeline_type": "advanced", "name": "SaaS Procurement Manager", "type": "B2B", "primary_use_case": "SALES_ENABLEMENT", "buying_stage": "DECISION", "decision_role": "ECONOMIC_BUYER", "committee_mapping": ["CTO", "CFO", "Legal"], "mcda_weights": { "price": 4, "timeToValue": 3, "risk": 5, "proof": 4, "support": 3, "quality": 4 }, "goals": ["Reduce software costs", "Consolidate vendors"], "pains": ["Budget tracking", "Contract renewals", "Shadow IT"], "triggers": ["Audit findings", "Budget review", "Contract expiration"], "values": ["Transparency", "Efficiency", "Compliance"], "objections": ["Integration complexity", "Training overhead"], "proof_preferences": ["Security certifications", "Compliance reports"], "brand_voice_fit": "CONSERVATIVE", "reading_level": "TECHNICAL", "role_title": "Procurement Manager", "seniority": "Senior", "industry": "Technology", "company_size": "SIZE_201_1K", "budget_authority": "SHARED", "alternatives": ["Competitor A", "Manual process"], "key_differentiators": ["SOC2 compliance", "API-first"] } ) persona = response.json() print(f"Created: {persona['name']} ({persona['id']})") print(f"Credits charged: {persona['credits_charged']}") components: schemas: CreateCustomPersonaRequest: description: >- Create a custom persona using one of three pipeline types. Each pipeline has different required fields - see the individual schemas for details. oneOf: - $ref: '#/components/schemas/NorthStarPersonaRequest' - $ref: '#/components/schemas/IntermediatePersonaRequest' - $ref: '#/components/schemas/AdvancedPersonaRequest' discriminator: propertyName: pipeline_type mapping: north_star: $ref: '#/components/schemas/NorthStarPersonaRequest' intermediate: $ref: '#/components/schemas/IntermediatePersonaRequest' advanced: $ref: '#/components/schemas/AdvancedPersonaRequest' CustomPersonaResponse: type: object properties: id: type: string description: Unique persona ID. object: type: string enum: - custom_persona example: custom_persona name: type: string category: type: string description: type: string pipeline_type: type: string enum: - north_star - intermediate - advanced type: type: string enum: - B2B - B2C nullable: true is_custom: type: boolean example: true created_at: type: integer description: Unix timestamp. credits_charged: type: integer description: Credits charged for creation. example: 300 details: $ref: '#/components/schemas/CustomPersonaDetails' ai_generated: type: object nullable: true properties: confidence: type: number rationale: type: string 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 NorthStarPersonaRequest: type: object description: >- North Star pipeline: AI-guided persona creation from suggestions. Use this after getting suggestions from /personas/suggestions endpoint. required: - pipeline_type - suggestion properties: pipeline_type: type: string enum: - north_star description: Must be 'north_star' for this pipeline. example: north_star suggestion: type: object description: >- REQUIRED: The selected suggestion from /personas/suggestions endpoint. required: - name - type properties: name: type: string description: Suggested persona name. type: type: string enum: - B2B - B2C description: Persona type. description: type: string goals: type: array items: type: string pains: type: array items: type: string channels: type: array items: type: string triggers: type: array items: type: string buying_stage: type: string decision_role: type: string confidence: type: number rationale: type: string business_description: type: string description: Original business description (optional, for context). target_customers: type: array items: type: string description: Original target customers (optional). sources: type: array description: Optional sources for additional context. items: type: object properties: type: type: string enum: - FILE - URL name: type: string url: type: string description: type: string IntermediatePersonaRequest: type: object description: >- Intermediate pipeline: Manual persona creation with AI-powered enrichment. Provide basic persona info and the AI will generate additional details. required: - pipeline_type - name - type - goals - pains properties: pipeline_type: type: string enum: - intermediate description: Must be 'intermediate' for this pipeline. example: intermediate name: type: string minLength: 2 maxLength: 100 description: 'REQUIRED: Persona name.' example: Enterprise CMO type: type: string enum: - B2B - B2C description: 'REQUIRED: Persona type.' example: B2B goals: type: array items: type: string minItems: 1 description: 'REQUIRED: Primary goals of the persona.' example: - Increase team productivity - Reduce operational costs pains: type: array items: type: string minItems: 1 description: 'REQUIRED: Pain points the persona experiences.' example: - Manual processes are slow - Lack of visibility into performance role_segment: type: array items: type: string description: Target roles or segments. buying_stage: type: string enum: - UNAWARE - PROBLEM_AWARE - SOLUTION_AWARE - DECISION description: Current stage in the buying journey. decision_role: type: string enum: - ECONOMIC_BUYER - CHAMPION - INFLUENCER - USER - BLOCKER description: Role in the buying decision. primary_objectives: type: array items: type: string description: Primary objectives. mcda_weights: type: object description: Multi-criteria decision weights (1-5 scale). properties: price: type: number minimum: 1 maximum: 5 timeToValue: type: number minimum: 1 maximum: 5 risk: type: number minimum: 1 maximum: 5 proof: type: number minimum: 1 maximum: 5 support: type: number minimum: 1 maximum: 5 triggers: type: array items: type: string description: Buying triggers. channels: type: array items: type: string description: Preferred channels. proof_types: type: array items: type: string description: Types of proof they trust. alternatives: type: array items: type: string description: Competitor alternatives. win_factors: type: array items: type: string description: Factors that win deals. objections: type: array items: type: string description: Common objections. sources: type: array items: type: object properties: type: type: string enum: - FILE - URL name: type: string url: type: string description: type: string role_title: type: string description: Job title (B2B). seniority: type: string description: Seniority level (B2B). industry: type: string description: Industry (B2B). company_size: type: string enum: - SIZE_1_50 - SIZE_51_200 - SIZE_201_1K - SIZE_1K_5K - SIZE_5K_PLUS description: Company size range (B2B). tech_stack: type: array items: type: string description: Technology stack (B2B). budget_authority: type: string enum: - NONE - RECOMMENDER - SHARED - FINAL description: Budget authority level (B2B). procurement_constraints: type: array items: type: string description: Procurement constraints (B2B). life_stage: type: string enum: - STUDENT - YOUNG_PROFESSIONAL - PARENT - RETIREE description: Life stage (B2C). age_band: type: string enum: - AGE_18_24 - AGE_25_34 - AGE_35_44 - AGE_45_54 - AGE_55_PLUS description: Age range (B2C). income_band: type: string enum: - UNDER_25K - INCOME_25K_50K - INCOME_50K_75K - INCOME_75K_100K - INCOME_100K_150K - INCOME_150K_PLUS description: Income range (B2C). household_context: type: array items: type: string description: Household context (B2C). lifestyle_affinities: type: array items: type: string description: Lifestyle interests (B2C). purchase_cadence: type: string enum: - IMPULSE - CONSIDERED - SEASONAL - SUBSCRIPTION description: Purchase behavior (B2C). AdvancedPersonaRequest: type: object description: >- Advanced pipeline: Full control over persona creation with all available fields. Best for power users who need granular customization. required: - pipeline_type - name - type - goals - pains properties: pipeline_type: type: string enum: - advanced description: Must be 'advanced' for this pipeline. example: advanced name: type: string minLength: 2 maxLength: 100 description: 'REQUIRED: Persona name.' example: Enterprise IT Director type: type: string enum: - B2B - B2C description: 'REQUIRED: Persona type.' example: B2B goals: type: array items: type: string minItems: 1 description: 'REQUIRED: Primary goals of the persona.' example: - Increase team productivity - Reduce operational costs pains: type: array items: type: string minItems: 1 description: 'REQUIRED: Pain points the persona experiences.' example: - Manual processes are slow - Lack of visibility into performance primary_use_case: type: string enum: - ACQUISITION - PMM_POSITIONING - CONTENT_SEO - SALES_ENABLEMENT - RETENTION_CS - RESEARCH description: Primary use case for this persona. example: ACQUISITION buying_stage: type: string enum: - UNAWARE - PROBLEM_AWARE - SOLUTION_AWARE - DECISION description: Current stage in the buying journey. example: SOLUTION_AWARE role_segment: type: array items: type: string description: Target roles or segments. decision_role: type: string enum: - ECONOMIC_BUYER - CHAMPION - INFLUENCER - USER - BLOCKER description: Role in the buying decision. primary_objectives: type: array items: type: string description: Primary objectives. mcda_weights: type: object description: >- Multi-criteria decision weights (1-5 scale). Advanced includes 'quality'. properties: price: type: number minimum: 1 maximum: 5 timeToValue: type: number minimum: 1 maximum: 5 risk: type: number minimum: 1 maximum: 5 proof: type: number minimum: 1 maximum: 5 support: type: number minimum: 1 maximum: 5 quality: type: number minimum: 1 maximum: 5 description: Advanced only. triggers: type: array items: type: string description: Buying triggers. channels: type: array items: type: string description: Preferred channels. proof_types: type: array items: type: string description: Types of proof they trust. alternatives: type: array items: type: string description: Competitor alternatives. win_factors: type: array items: type: string description: Factors that win deals. objections: type: array items: type: string description: Common objections. sources: type: array items: type: object properties: type: type: string enum: - FILE - URL name: type: string url: type: string description: type: string values: type: array items: type: string description: Core values (advanced only). proof_preferences: type: array items: type: string description: Proof preferences (advanced only). brand_voice_fit: type: string enum: - CONSERVATIVE - BALANCED - BOLD description: Brand voice alignment (advanced only). reading_level: type: string enum: - SIMPLE - STANDARD - TECHNICAL description: Content reading level (advanced only). tone_guardrails: type: array items: type: string description: Tone restrictions (advanced only). key_differentiators: type: array items: type: string description: Key differentiators (advanced only). regulatory_context: type: array items: type: string description: Regulatory considerations (advanced only). localization: type: object description: Geographic localization settings (advanced only). properties: enabled: type: boolean scope: type: string enum: - COUNTRY - REGION - STATE - CITY - ZIP value: type: string channels: type: array items: type: string objections: type: array items: type: string keywords: type: array items: type: string price_sensitivity_delta: type: number purpose_packs: type: object description: Purpose-specific configurations (advanced only). properties: enabled: type: object properties: acquisition: type: boolean pmm: type: boolean content: type: boolean sales: type: boolean research: type: boolean acquisition: type: object pmm: type: object content: type: object sales: type: object research: type: object role_title: type: string description: Job title (B2B). seniority: type: string description: Seniority level (B2B). industry: type: string description: Industry (B2B). company_size: type: string enum: - SIZE_1_50 - SIZE_51_200 - SIZE_201_1K - SIZE_1K_5K - SIZE_5K_PLUS description: Company size range (B2B). tech_stack: type: array items: type: string description: Technology stack (B2B). budget_authority: type: string enum: - NONE - RECOMMENDER - SHARED - FINAL description: Budget authority level (B2B). procurement_constraints: type: array items: type: string description: Procurement constraints (B2B). committee_mapping: type: array items: type: string description: Buying committee roles (B2B advanced). life_stage: type: string enum: - STUDENT - YOUNG_PROFESSIONAL - PARENT - RETIREE description: Life stage (B2C). age_band: type: string enum: - AGE_18_24 - AGE_25_34 - AGE_35_44 - AGE_45_54 - AGE_55_PLUS description: Age range (B2C). income_band: type: string enum: - UNDER_25K - INCOME_25K_50K - INCOME_50K_75K - INCOME_75K_100K - INCOME_100K_150K - INCOME_150K_PLUS description: Income range (B2C). household_context: type: array items: type: string description: Household context (B2C). lifestyle_affinities: type: array items: type: string description: Lifestyle interests (B2C). purchase_cadence: type: string enum: - IMPULSE - CONSIDERED - SEASONAL - SUBSCRIPTION description: Purchase behavior (B2C). CustomPersonaDetails: type: object description: Detailed custom persona fields. properties: pipeline_type: type: string persona_type: type: string primary_use_case: type: string buying_stage: type: string decision_role: type: string role_segment: type: array items: type: string primary_objectives: type: array items: type: string mcda_weights: type: object goals: type: array items: type: string pains: type: array items: type: string triggers: type: array items: type: string channels: type: array items: type: string proof_types: type: array items: type: string alternatives: type: array items: type: string win_factors: type: array items: type: string objections: type: array items: type: string values: type: array items: type: string proof_preferences: type: array items: type: string brand_voice_fit: type: string reading_level: type: string tone_guardrails: type: array items: type: string role_title: type: string seniority: type: string industry: type: string company_size: type: string tech_stack: type: array items: type: string budget_authority: type: string procurement_constraints: type: array items: type: string committee_mapping: type: array items: type: string life_stage: type: string age_band: type: string income_band: type: string household_context: type: array items: type: string lifestyle_affinities: type: array items: type: string purchase_cadence: type: string key_differentiators: type: array items: type: string regulatory_context: type: array items: type: string is_localized: type: boolean locale_scope: type: string locale_value: type: string local_channels: type: array items: type: string local_objections: type: array items: type: string local_keywords: type: array items: type: string price_sensitivity_delta: type: number purpose_packs_enabled: type: object acquisition_config: type: object pmm_config: type: object content_config: type: object sales_config: type: object research_config: type: object securitySchemes: BearerAuth: type: http scheme: bearer description: >- API key prefixed with `mvra_live_`. Create keys at **Settings > Developer > API Keys**. ````