> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognigy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a new brand persona

> Creates a new brand persona with the provided information.



## OpenAPI

````yaml https://api-trial.cognigy.ai/swagger/openapi.json post /agentpersonas
openapi: 3.0.3
info:
  contact:
    email: support@example.com
    name: API Support
  description: API for managing agents and related resources
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: http://swagger.io/terms/
  title: Agents API
  version: '1.0'
servers:
  - url: https://api-trial.cognigy.ai/v1
security:
  - ApiKey: []
tags:
  - name: Agents
  - name: Brand personas
  - name: Tools
  - name: Built-in tools
  - name: Skills
  - name: Built-in skills
  - name: MCP servers
  - name: Tool references
paths:
  /agentpersonas:
    post:
      tags:
        - Brand personas
      summary: Create a new brand persona
      description: Creates a new brand persona with the provided information.
      requestBody:
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/internal_agentpersonas.CreateAgentPersonaRequest
        description: Brand persona data
        required: true
        x-originalParamName: agentpersona
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/internal_agentpersonas.CreateAgentPersonaResponse
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailBadRequest
          description: Invalid request body or validation error
        '403':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailForbidden
          description: Access denied
        '409':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailConflict
          description: A brand persona with this name already exists in this project
        '500':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailInternalError
          description: Internal server error
components:
  schemas:
    internal_agentpersonas.CreateAgentPersonaRequest:
      properties:
        description:
          type: string
        image:
          type: string
        imageOptimizedFormat:
          type: boolean
        name:
          type: string
        projectId:
          type: string
        speakingStyle:
          $ref: '#/components/schemas/internal_agentpersonas.SpeakingStyle'
        voiceConfig:
          allOf:
            - $ref: '#/components/schemas/internal_agentpersonas.VoiceConfig'
          description: >-
            Deprecated: voice settings are moving to the agent's own

            `voice-config-defaults` builtin tool instance, which is per-agent

            (a persona is a brand identity several agents share, while call

            behaviour is not). The persona keeps name, description, speaking
            style

            and avatar. Still read as a fallback for the <channel> block's
            language

            when the agent has no baseline; still required on create, so
            removing

            it is a coordinated breaking change rather than a tidy-up. See

            planning/plans/voice-native-poc/agent-voice-configs-plan.md.
      required:
        - name
        - projectId
        - speakingStyle
        - voiceConfig
      type: object
    internal_agentpersonas.CreateAgentPersonaResponse:
      properties:
        createdAt:
          type: integer
        createdBy:
          example: 507f1f77bcf86cd799439011
          type: string
        description:
          type: string
        id:
          example: 507f1f77bcf86cd799439011
          type: string
        image:
          type: string
        imageOptimizedFormat:
          type: boolean
        lastChangedAt:
          type: integer
        lastChangedBy:
          example: 507f1f77bcf86cd799439011
          type: string
        name:
          type: string
        organisationId:
          example: 507f1f77bcf86cd799439011
          type: string
        projectId:
          example: 507f1f77bcf86cd799439011
          type: string
        referenceId:
          type: string
        speakingStyle:
          $ref: '#/components/schemas/internal_agentpersonas.SpeakingStyle'
        voiceConfig:
          allOf:
            - $ref: '#/components/schemas/internal_agentpersonas.VoiceConfig'
          description: >-
            Deprecated: voice settings are moving to the agent's own

            `voice-config-defaults` builtin tool instance, which is per-agent

            (a persona is a brand identity several agents share, while call

            behaviour is not). The persona keeps name, description, speaking
            style

            and avatar. Still read as a fallback for the <channel> block's
            language

            when the agent has no baseline; still required on create, so
            removing

            it is a coordinated breaking change rather than a tidy-up. See

            planning/plans/voice-native-poc/agent-voice-configs-plan.md.
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailBadRequest:
      properties:
        detail:
          example: request body validation failed
          type: string
        errors:
          items:
            $ref: >-
              #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.FieldError
          type: array
        instance:
          example: /v1/{resource}
          type: string
        status:
          example: 400
          type: integer
        title:
          example: Bad Request
          type: string
        traceId:
          example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed
          type: string
        type:
          example: about:blank
          type: string
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailForbidden:
      properties:
        detail:
          example: 'access denied: insufficient permissions'
          type: string
        instance:
          example: /v1/{resource}/{id}
          type: string
        status:
          example: 403
          type: integer
        title:
          example: Forbidden
          type: string
        traceId:
          example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed
          type: string
        type:
          example: about:blank
          type: string
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailConflict:
      properties:
        detail:
          example: a resource with this identifier already exists
          type: string
        instance:
          example: /v1/{resource}
          type: string
        status:
          example: 409
          type: integer
        title:
          example: Conflict
          type: string
        traceId:
          example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed
          type: string
        type:
          example: about:blank
          type: string
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailInternalError:
      properties:
        detail:
          example: internal server error
          type: string
        instance:
          example: /v1/{resource}
          type: string
        status:
          example: 500
          type: integer
        title:
          example: Internal Server Error
          type: string
        traceId:
          example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed
          type: string
        type:
          example: about:blank
          type: string
      type: object
    internal_agentpersonas.SpeakingStyle:
      properties:
        completeness:
          type: string
        customInstructions:
          type: string
        formality:
          type: string
        useCustomInstructions:
          type: boolean
      type: object
    internal_agentpersonas.VoiceConfig:
      properties:
        ttsDisableCache:
          type: boolean
        ttsLabel:
          type: string
        ttsLanguage:
          type: string
        ttsModel:
          type: string
        ttsVendor:
          type: string
        ttsVoice:
          type: string
      required:
        - ttsLabel
        - ttsModel
        - ttsVendor
        - ttsVoice
      type: object
    github_com_cognigy_ai-agents-v2_internal_middleware.FieldError:
      properties:
        field:
          type: string
        message:
          type: string
      type: object
  securitySchemes:
    ApiKey:
      description: '[Production] API key for production authentication'
      in: header
      name: X-API-Key
      type: apiKey

````