> ## 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 brand voice > Create a new brand voice by providing source materials (URLs and/or documents). The AI will analyze the content and generate a brand voice profile. Processing happens asynchronously - poll the GET endpoint to check status. ## OpenAPI ````yaml /openapi.json post /brand-voices 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: /brand-voices: post: tags: - Brand Voice summary: Create brand voice description: >- Create a new brand voice by providing source materials (URLs and/or documents). The AI will analyze the content and generate a brand voice profile. Processing happens asynchronously - poll the GET endpoint to check status. operationId: createBrandVoice requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBrandVoiceRequest' responses: '201': description: >- Brand voice created successfully. Status will be 'pending' until processing completes. content: application/json: schema: $ref: '#/components/schemas/BrandVoice' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication error 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 source: |- curl -X POST https://app.mavera.io/api/v1/brand-voices \ -H "Authorization: Bearer mvra_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "label": "Acme Brand Voice", "urls": ["https://acme.com/about", "https://acme.com/blog"], "usage_context": "Marketing content and social media" }' - lang: python label: Python source: >- import requests import time headers = {"Authorization": "Bearer mvra_live_your_key_here"} # Create brand voice response = requests.post( "https://app.mavera.io/api/v1/brand-voices", headers=headers, json={ "label": "Acme Brand Voice", "urls": ["https://acme.com/about", "https://acme.com/blog"], "usage_context": "Marketing content and social media" } ) brand_voice = response.json() print(f"Created: {brand_voice['id']} (Status: {brand_voice['status']})") # Poll for completion while brand_voice["status"] in ["pending", "generating"]: time.sleep(5) brand_voice = requests.get( f"https://app.mavera.io/api/v1/brand-voices/{brand_voice['id']}", headers=headers ).json() print(f"Status: {brand_voice['status']}") print(f"Tone: {brand_voice['tone']}") components: schemas: CreateBrandVoiceRequest: type: object required: - label - usage_context properties: label: type: string minLength: 2 description: Display name for the brand voice usage_context: type: string minLength: 10 description: Description of how this brand voice will be used workspace_id: type: string description: Target workspace ID (uses default workspace if not specified) urls: type: array items: $ref: '#/components/schemas/CreateBrandVoiceUrlInput' description: URLs to analyze for brand voice extraction documents: type: array items: $ref: '#/components/schemas/CreateBrandVoiceDocumentInput' description: Documents to analyze for brand voice extraction user_examples: type: array items: type: object properties: use_case: type: string example: type: string description: Example phrases you want the brand voice to use user_vocabulary: type: object properties: preferred_terms: type: array items: type: string description: Words/phrases to always use avoid_terms: type: array items: type: string description: Words/phrases to never use description: Vocabulary preferences user_tone: type: object properties: adjectives: type: array items: type: string description: Tone adjectives (e.g., 'professional', 'casual') dos: type: array items: type: string description: Things to do donts: type: array items: type: string description: Things to avoid description: Tone preferences BrandVoice: type: object description: A brand voice profile for content generation properties: id: type: string description: Unique brand voice identifier object: type: string enum: - brand_voice label: type: string description: Display name for the brand voice usage_context: type: string description: Description of how this brand voice should be used status: $ref: '#/components/schemas/BrandVoiceStatus' error: type: string nullable: true description: Error message if status is failed voice_summary: type: string nullable: true description: AI-generated summary of the brand voice tone: $ref: '#/components/schemas/BrandVoiceTone' writing_style: $ref: '#/components/schemas/BrandVoiceWritingStyle' vocabulary: $ref: '#/components/schemas/BrandVoiceVocabulary' example_phrases: type: array nullable: true items: type: object properties: use_case: type: string example: type: string description: Example phrases demonstrating the brand voice sources: $ref: '#/components/schemas/BrandVoiceSources' workspace_id: type: string created_at: type: string format: date-time updated_at: type: string format: date-time 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 CreateBrandVoiceUrlInput: type: object required: - url - name properties: url: type: string format: uri description: URL to extract content from name: type: string description: Display name for the URL description: type: string description: Optional description of the content extracted_content: type: string description: Pre-extracted content (optional) CreateBrandVoiceDocumentInput: type: object required: - name - url - file_type - file_size properties: name: type: string description: Document name url: type: string format: uri description: URL to the uploaded document description: type: string description: Optional description file_type: type: string description: File MIME type file_size: type: integer description: File size in bytes extracted_content: type: string description: Pre-extracted content (optional) BrandVoiceStatus: type: string enum: - pending - generating - completed - failed description: Current processing status of the brand voice BrandVoiceTone: type: object description: Tone guidelines for the brand voice properties: adjectives: type: array items: type: string description: >- Adjectives that describe the brand tone (e.g., 'professional', 'friendly') dos: type: array items: type: string description: Things to do when writing (e.g., 'Use active voice') donts: type: array items: type: string description: Things to avoid when writing (e.g., 'Don't use jargon') BrandVoiceWritingStyle: type: object description: Writing style guidelines properties: sentence_structure: type: string nullable: true description: Preferred sentence structure (e.g., 'Short, punchy sentences') jargon_usage: type: string nullable: true description: Guidelines for technical jargon usage BrandVoiceVocabulary: type: object description: Vocabulary preferences properties: preferred_terms: type: array items: type: string description: Words and phrases to use avoid_terms: type: array items: type: string description: Words and phrases to avoid BrandVoiceSources: type: object description: Source materials used to generate the brand voice properties: urls: type: array items: $ref: '#/components/schemas/BrandVoiceUrl' documents: type: array items: $ref: '#/components/schemas/BrandVoiceDocument' BrandVoiceUrl: type: object properties: id: type: string url: type: string format: uri name: type: string description: type: string nullable: true BrandVoiceDocument: type: object properties: id: type: string name: type: string description: type: string nullable: true file_type: type: string file_size: type: integer securitySchemes: BearerAuth: type: http scheme: bearer description: >- API key prefixed with `mvra_live_`. Create keys at **Settings > Developer > API Keys**. ````