> ## 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.

# Update a custom persona

> Update fields of a custom persona. Only custom personas can be modified - base personas are read-only. You can update the name, description, and any custom persona fields.



## OpenAPI

````yaml /openapi.json patch /personas/{id}
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/{id}:
    patch:
      tags:
        - Custom Personas
      summary: Update a custom persona
      description: >-
        Update fields of a custom persona. Only custom personas can be modified
        - base personas are read-only. You can update the name, description, and
        any custom persona fields.
      operationId: updateCustomPersona
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The persona ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomPersonaRequest'
      responses:
        '200':
          description: Persona updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomPersonaResponse'
        '400':
          description: Validation error or cannot update base persona.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Persona not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
        - lang: curl
          label: cURL
          source: >-
            curl -X PATCH https://app.mavera.io/api/v1/personas/YOUR_PERSONA_ID
            \
              -H "Authorization: Bearer mvra_live_your_key_here" \
              -H "Content-Type: application/json" \
              -d '{
                "name": "Updated Persona Name",
                "goals": ["New goal 1", "New goal 2"],
                "pains": ["Updated pain point"]
              }'
components:
  schemas:
    UpdateCustomPersonaRequest:
      type: object
      description: >-
        Update an existing custom persona. All fields are optional - only
        include fields you want to change.
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 100
        description:
          type: string
        goals:
          type: array
          items:
            type: string
        pains:
          type: array
          items:
            type: string
        triggers:
          type: array
          items:
            type: string
        channels:
          type: array
          items:
            type: string
        objections:
          type: array
          items:
            type: string
        values:
          type: array
          items:
            type: string
        proof_preferences:
          type: array
          items:
            type: string
        tone_guardrails:
          type: array
          items:
            type: string
        alternatives:
          type: array
          items:
            type: string
        win_factors:
          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
        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
    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
    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**.

````