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

# Create or change an A/B variant

> Sets the settings a variant replaces, creating the variant if the key is new. A new variant receives no traffic until setAbTraffic gives it some, so creating one never reaches a customer. The body is a merge patch shaped like updateProjectSettings: send only the settings to change, nested as getProjectSettings returns them, and `null` to stop overriding one. Only settings these credentials may write are accepted, and the result is validated and checked to run exactly as written before it is saved. Settings the background jobs read from the project itself (follow-up, resolution and unanswered escalation timing) are refused, since a variant would not change them. Try a variant on a single conversation first with runPlayground and its `abKey`. A change to a variant already receiving traffic takes effect at once, from the next message of every conversation running it, ongoing ones included.



## OpenAPI

````yaml /api-reference/specs/claudia/v1.json patch /v1/projects/{project}/ab-test/variants/{key}
openapi: 3.0.1
info:
  title: Claudia API
  version: 1.0.0
servers:
  - url: https://api.cloudhumans.com/claudia
    description: Production
  - url: https://api.cloudhumans.com/claudia/staging
    description: Staging
security:
  - bearerAuth: []
tags:
  - name: MCP Servers
    description: >-
      The MCP servers your agents can call tools on. Registering one here is
      what makes its tools selectable in an agent; the credentials it needs are
      stored encrypted and never read back.
  - name: Knowledge Base Content
    description: Read, search and edit the content that answers your customers.
  - name: Content Quality
    description: Rewrites proposed for content that is answering your customers badly.
  - name: Playground
    description: >-
      Talk to one of your agents as if you were a customer, without touching a
      real conversation.
  - name: Project Settings
    description: >-
      Read and change how a ClaudIA project behaves — the settings screens of
      the ClaudIA app, as an API.
  - name: Content Improvements
    description: Answers Claudia proposes for questions your content does not cover yet.
  - name: Knowledge Bases
    description: The knowledge bases your account can manage.
  - name: Content Sources
    description: The sites Claudia crawls to keep a knowledge base in sync.
  - name: Agents
    description: >-
      The AI agents (assistants) configured for your tenant: the orchestrator
      (supervisor) and its specialists (react). Reads answer the same
      passthrough shape the platform stores; creates land as DRAFTS a human
      reviews and publishes in the app.
  - name: Agent Tools
    description: >-
      The tool catalog your agents can be given, aggregated across every MCP
      server registered for the tenant. This is the same catalog an assistant's
      mcp_servers[].tools whitelist is validated against.
  - name: Conversations
    description: >-
      Read access to a conversation's lean investigation summary — messages,
      status and resolution — and the execution trace behind one of its
      processed messages, without the internal processing state the hub UI's
      full read carries.
paths:
  /v1/projects/{project}/ab-test/variants/{key}:
    patch:
      tags:
        - A/B Tests
      summary: Create or change an A/B variant
      description: >-
        Sets the settings a variant replaces, creating the variant if the key is
        new. A new variant receives no traffic until setAbTraffic gives it some,
        so creating one never reaches a customer. The body is a merge patch
        shaped like updateProjectSettings: send only the settings to change,
        nested as getProjectSettings returns them, and `null` to stop overriding
        one. Only settings these credentials may write are accepted, and the
        result is validated and checked to run exactly as written before it is
        saved. Settings the background jobs read from the project itself
        (follow-up, resolution and unanswered escalation timing) are refused,
        since a variant would not change them. Try a variant on a single
        conversation first with runPlayground and its `abKey`. A change to a
        variant already receiving traffic takes effect at once, from the next
        message of every conversation running it, ongoing ones included.
      operationId: upsertAbVariant
      parameters:
        - name: project
          in: path
          description: >-
            The ClaudIA project to act on, by name. Get the names from
            listMyClaudiaProjects — a project these credentials do not cover
            answers 404, indistinguishable from one that does not exist.
          required: true
          schema:
            type: string
        - name: key
          in: path
          description: >-
            The variant to act on, 1 to 64 letters, digits, `_` or `-`.
            getProjectAbTest lists the existing ones.
          required: true
          schema:
            type: string
          example: short_summary
        - name: accountId
          in: query
          description: >-
            The CloudChat account whose permissions decide what you may read and
            write here, e.g. `7`. It is permission context, not the resource:
            the project is named in the path. Only unique within an instance, so
            it is always read together with the `cloudchat-instance` header —
            get the pair from listMyCloudChatAccounts. An account your
            credentials hold no editing claim for answers 403.
          required: true
          schema:
            type: string
        - name: cloudchat-instance
          in: header
          description: >-
            The CloudChat instance the account lives in, e.g. `4`. Sent as a
            header, and required: with `accountId` it forms the pair that names
            exactly one account, which `accountId` alone does not.
            listMyCloudChatAccounts returns the value to send here alongside
            each accountId.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditableProjectSettings'
        required: true
      responses:
        '200':
          description: Saved. The whole A/B test is returned as it now stands.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectAbTest'
        '400':
          description: >-
            A key that is not valid, a setting that cannot vary between
            variants, or overrides that would not run as written or break a
            settings rule. Nothing was saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectAbTestRefused'
        '401':
          description: Missing, expired or invalid credentials.
        '403':
          description: >-
            The patch names settings this role cannot write, or the variant
            already overrides some. Nothing was saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectAbTestRefused'
        '404':
          description: >-
            No such resource, or none these credentials can reach — the two are
            deliberately indistinguishable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            `concurrent_change`: someone else changed the A/B test since it was
            read. Nothing was saved; read it again with getProjectAbTest and
            redo the change on top of what is there now.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectAbTestRefused'
        '429':
          description: Rate limit applied by the API gateway. Back off and retry.
components:
  schemas:
    EditableProjectSettings:
      type: object
      properties:
        displayName:
          type: string
        knowledgeBases:
          type: array
          items:
            type: string
        summaryPrompt:
          type: string
        confidenceThreshold:
          type: number
          format: float
        lowConfidenceCountLimit:
          type: integer
          format: int32
        maximumMinutesWithoutResponse:
          type: integer
          format: int64
        resolutionJobActive:
          type: boolean
        detectTransferMessage:
          type: boolean
        outOfOfficeResolveN1:
          type: boolean
        outOfOfficeMessage:
          type: string
        deferOutOfOfficeClose:
          type: boolean
        generatedOutOfOfficeMessage:
          type: boolean
        outOfOfficeAnswerPrompt:
          type: string
        forwardToHumanMessage:
          type: string
        humansAvailable:
          type: boolean
        filterN1TagsOnly:
          type: boolean
        filterN2TagsOnly:
          type: boolean
        enableAudioTranscription:
          type: boolean
        voiceReplyEnabled:
          type: boolean
        voiceReplyEngine:
          type: string
        voiceReplyVoice:
          type: string
        voiceReplyTextAfterAudioPauseMillis:
          type: integer
          format: int64
        repeatedSectionLimit:
          type: integer
          format: int32
        protocolFooterEnabled:
          type: boolean
        protocolFooterAverageResponseMinutes:
          type: integer
          format: int32
        shouldNeverChangeIntentWhenOnEddieFlow:
          type: boolean
        language:
          type: string
          enum:
            - PT_BR
            - EN
            - ES
            - FR
            - DE
            - IT
            - JA
            - KO
            - ZH
            - RU
            - AR
            - HI
            - NL
            - SV
            - DA
            - FI
            - PL
            - TR
            - TH
            - VI
            - MS
            - TL
            - ID
        basePromptModules:
          $ref: '#/components/schemas/BasePromptModulesSettings'
        outputTransformation:
          $ref: '#/components/schemas/OutputTransformationSettings'
        splitLargeMessages:
          $ref: '#/components/schemas/SplitLargeMessagesSettings'
        enlightenmentQuestionLimit:
          $ref: '#/components/schemas/EnlightenmentQuestionLimitSettings'
        classificationSettings:
          $ref: '#/components/schemas/ClassificationSettings'
        greetingsSettings:
          $ref: '#/components/schemas/GreetingsSettings'
        unansweredTicketEscalator:
          $ref: '#/components/schemas/UnansweredTicketEscalator'
        attachmentHandover:
          $ref: '#/components/schemas/AttachmentHandoverSettings'
        startWithBotConfiguration:
          $ref: '#/components/schemas/StartWithBotConfiguration'
        endWithBotConfiguration:
          $ref: '#/components/schemas/EndWithBotConfiguration'
        defaultTagConfiguration:
          $ref: '#/components/schemas/DefaultTagConfiguration'
        llmTagConfiguration:
          $ref: '#/components/schemas/LlmTagConfiguration'
        agenticLLMTagConfiguration:
          $ref: '#/components/schemas/AgenticLLMTagConfiguration'
        imageTranscriptionSettings:
          $ref: '#/components/schemas/ImageTranscriptionSettings'
        eddieConfiguration:
          $ref: '#/components/schemas/EddieConfiguration'
        backofficeConfiguration:
          $ref: '#/components/schemas/BackofficeConfiguration'
        frustrationDetection:
          $ref: '#/components/schemas/FrustrationDetection'
        contextEnrichment:
          $ref: '#/components/schemas/ContextEnrichmentSettings'
        resolutionMessages:
          $ref: '#/components/schemas/ResolutionMessagesSettings'
        humanOfficeHoursConfig:
          $ref: '#/components/schemas/HumanOfficeHoursConfigSettings'
        problemResolvedChecker:
          $ref: '#/components/schemas/ProblemResolvedCheckerSettings'
        botPromotingConfig:
          $ref: '#/components/schemas/BotPromotingConfigSettings'
        forwardToHumanChecker:
          $ref: '#/components/schemas/ForwardToHumanCheckerSettings'
    ProjectAbTest:
      required:
        - baselinePercentage
        - variants
      type: object
      properties:
        baselinePercentage:
          type: integer
          description: >-
            Share of new conversations that run the base configuration, in
            percent.
          format: int32
          example: 80
        variants:
          type: array
          description: >-
            Every variant this project declares, including the ones receiving no
            traffic.
          items:
            $ref: '#/components/schemas/ProjectAbVariant'
      description: >-
        How this project's conversations are split between its base
        configuration and each A/B variant. Every new conversation draws once
        and keeps the variant it drew until it ends, always running that
        variant's current settings.
    ProjectAbTestRefused:
      required:
        - error
        - reason
      type: object
      properties:
        error:
          type: string
          description: What went wrong.
          example: The base share does not match the variants' traffic
        reason:
          type: string
          description: >-
            Machine-readable cause: `invalid_key`, `unknown_variant`,
            `locked_variant`, `not_overridable`, `forbidden_fields`,
            `not_applicable`, `invalid_settings`, `percentage_out_of_range`,
            `traffic_over_100`, `baseline_mismatch`, `variant_live` or
            `concurrent_change`.
          example: baseline_mismatch
        keys:
          type: array
          description: >-
            The variant keys or dotted setting paths the refusal is about, when
            it names any.
          items:
            type: string
            description: >-
              The variant keys or dotted setting paths the refusal is about,
              when it names any.
        expectedBaselinePercentage:
          type: integer
          description: >-
            On `baseline_mismatch`: the base share these percentages actually
            leave.
          format: int32
          example: 80
        violations:
          type: array
          description: 'On `invalid_settings`: every rule the overrides broke.'
          items:
            $ref: '#/components/schemas/ProjectSettingsViolation'
      description: The change was refused and nothing was saved.
    Error:
      required:
        - error
      type: object
      properties:
        error:
          type: string
          description: What went wrong.
          example: 'Forbidden: token holds no claim for the requested account'
      description: Something the caller needs to fix.
    BasePromptModulesSettings:
      type: object
      properties:
        enabled:
          type: boolean
        modules:
          type: object
          additionalProperties:
            type: string
    OutputTransformationSettings:
      type: object
      properties:
        enabled:
          type: boolean
        fallbackResponseLanguage:
          type: string
        minCharsForLanguageDetection:
          type: integer
          format: int32
        languages:
          type: array
          items:
            type: string
            enum:
              - PT_BR
              - EN
              - ES
              - FR
              - DE
              - IT
              - JA
              - KO
              - ZH
              - RU
              - AR
              - HI
              - NL
              - SV
              - DA
              - FI
              - PL
              - TR
              - TH
              - VI
              - MS
              - TL
              - ID
    SplitLargeMessagesSettings:
      type: object
      properties:
        splitLargeMessagesActive:
          type: boolean
        chunkSize:
          type: integer
          format: int32
        timeBetweenMessages:
          type: integer
          format: int64
    EnlightenmentQuestionLimitSettings:
      type: object
      properties:
        enabled:
          type: boolean
        sentence:
          type: string
        limit:
          type: integer
          format: int32
    ClassificationSettings:
      type: object
      properties:
        enabled:
          type: boolean
        classificationPrompt:
          type: string
        clarificationAgentPrompt:
          type: string
        noValidContentAgentPrompt:
          type: string
        maxNoValidContentAttempts:
          type: integer
          format: int32
        maxClarificationAttempts:
          type: integer
          format: int32
    GreetingsSettings:
      type: object
      properties:
        firstInteraction:
          type: string
        n2Greeting:
          type: string
        staticGreeting:
          type: string
        staticGreetingEnabled:
          type: boolean
        default:
          type: string
    UnansweredTicketEscalator:
      type: object
      properties:
        jobActive:
          type: boolean
        staticHandoverMessage:
          type: string
        tag:
          type: string
        escalatorTryCountLimit:
          type: integer
          format: int32
        minutesWithoutResponse:
          type: integer
          format: int64
    AttachmentHandoverSettings:
      type: object
      properties:
        enabled:
          type: boolean
        attachmentRegex:
          type: string
        message:
          type: string
    StartWithBotConfiguration:
      type: object
      properties:
        enabled:
          type: boolean
        flowId:
          type: string
        addIntentToN2Tag:
          type: boolean
    EndWithBotConfiguration:
      type: object
      properties:
        onCloseEnabled:
          type: boolean
        onCloseFlowId:
          type: string
        onN2Enabled:
          type: boolean
        onN2FlowId:
          type: string
    DefaultTagConfiguration:
      type: object
      properties:
        active:
          type: boolean
        n1DefaultTag:
          type: string
        n2DefaultTag:
          type: string
        useClarificationSections:
          type: boolean
    LlmTagConfiguration:
      type: object
      properties:
        active:
          type: boolean
        prompt:
          type: string
    AgenticLLMTagConfiguration:
      type: object
      properties:
        active:
          type: boolean
    ImageTranscriptionSettings:
      type: object
      properties:
        enabled:
          type: boolean
        prompt:
          type: string
    EddieConfiguration:
      type: object
      properties:
        maxRepeatPerFlow:
          type: integer
          format: int32
        maxRepeatTransfer:
          type: boolean
    BackofficeConfiguration:
      type: object
      properties:
        errorMessage:
          type: string
    FrustrationDetection:
      type: object
      properties:
        enabled:
          type: boolean
        frustrationThreshold:
          type: integer
          format: int32
        handoverMessage:
          type: string
    ContextEnrichmentSettings:
      type: object
      properties:
        contactData:
          $ref: '#/components/schemas/ContactDataEnrichmentSettings'
        previousConversations:
          $ref: '#/components/schemas/PreviousConversationsEnrichmentSettings'
        customContext:
          $ref: '#/components/schemas/CustomContextEnrichmentSettings'
    ResolutionMessagesSettings:
      type: object
      properties:
        resolutionMessageWithUserFeedback:
          type: string
        resolutionMessageForNoUserFeedback:
          type: string
    HumanOfficeHoursConfigSettings:
      type: object
      properties:
        regularRules:
          type: array
          items:
            $ref: '#/components/schemas/HumanOfficeHoursRegularRuleSettings'
        specialDates:
          type: array
          items:
            $ref: '#/components/schemas/HumanOfficeHoursSpecialDateSettings'
    ProblemResolvedCheckerSettings:
      type: object
      properties:
        maximumMinutesWithoutResponse:
          type: integer
          format: int64
        problemResolvedQuestion:
          type: string
        jobActive:
          type: boolean
        autoDetectProblemSolved:
          type: boolean
        identifyProblemSolvedPrompt:
          type: string
        flowPrompt:
          $ref: '#/components/schemas/FlowPromptSettings'
        maxAttempts:
          type: integer
          format: int32
        retryIntervalMinutes:
          type: integer
          format: int64
        closeAfterMinutes:
          type: integer
          format: int64
        attemptMessages:
          type: array
          items:
            type: string
        followUpPrompt:
          type: string
    BotPromotingConfigSettings:
      type: object
      properties:
        enabled:
          type: boolean
        flowPrompt:
          $ref: '#/components/schemas/FlowPromptSettings'
    ForwardToHumanCheckerSettings:
      type: object
      properties:
        autoDetectForwardToHuman:
          type: boolean
        directHandoverAfterTurns:
          type: integer
          format: int32
        followUpMessage:
          type: string
        staticMessagesEnabled:
          type: boolean
        identifyForwardToHumanPrompt:
          type: string
        followUpPrompt:
          type: string
        forwardDirectlyPrompt:
          type: string
        directHandoverAfterEngagement:
          type: boolean
        evaluateOnEddieHandback:
          type: boolean
    ProjectAbVariant:
      required:
        - editable
        - hiddenOverrideCount
        - key
        - overrides
        - percentage
      type: object
      properties:
        key:
          type: string
          description: Identifies the variant. Also what runPlayground takes as `abKey`.
          example: short_summary
        percentage:
          type: integer
          description: >-
            Share of new conversations that run this variant, in percent. 0
            means paused.
          format: int32
          example: 20
        editable:
          type: boolean
          description: >-
            Whether these credentials may change this variant: edit it, change
            its traffic or delete it. A variant is editable only by someone who
            may write every setting it overrides.
        overrides:
          type: object
          additionalProperties: true
          description: >-
            The settings this variant replaces, nested as in getProjectSettings,
            limited to the ones these credentials may read.
          example:
            summaryPrompt: Resuma em uma frase.
        hiddenOverrideCount:
          type: integer
          description: >-
            How many overridden settings were left out of `overrides` because
            these credentials cannot read them. Above 0 means the variant
            changes more than what is shown.
          format: int32
          example: 0
      description: 'One A/B variant: the settings it replaces and the traffic it receives.'
    ProjectSettingsViolation:
      required:
        - params
        - path
        - ruleId
      type: object
      properties:
        path:
          type: string
          description: The dotted path the rule applies to.
          example: splitLargeMessages.chunkSize
        ruleId:
          type: string
          description: Which rule was broken.
          example: value_out_of_range
        params:
          type: object
          additionalProperties:
            type: object
            description: The rule's bounds or expected values, when it has any.
            example:
              min: 1
              max: 4096
          description: The rule's bounds or expected values, when it has any.
          example:
            min: 1
            max: 4096
      description: One rule the patch broke.
    ContactDataEnrichmentSettings:
      type: object
      properties:
        enabled:
          type: boolean
    PreviousConversationsEnrichmentSettings:
      type: object
      properties:
        enabled:
          type: boolean
        maxTickets:
          type: integer
          format: int32
    CustomContextEnrichmentSettings:
      type: object
      properties:
        activeWorkflowId:
          type: string
    HumanOfficeHoursRegularRuleSettings:
      required:
        - weekdays
      type: object
      properties:
        preset:
          type: string
          enum:
            - WEEKDAYS
            - SATURDAY
            - ALL_DAYS
            - CUSTOM
        weekdays:
          type: array
          items:
            type: string
            enum:
              - SU
              - MO
              - TU
              - WE
              - TH
              - FR
              - SA
        availability:
          type: string
          enum:
            - ACTIVE
            - UNAVAILABLE
        allDay:
          type: boolean
        startTime:
          type: string
        endTime:
          type: string
    HumanOfficeHoursSpecialDateSettings:
      type: object
      properties:
        name:
          type: string
        date:
          type: string
        availability:
          type: string
          enum:
            - ACTIVE
            - UNAVAILABLE
        allDay:
          type: boolean
        startTime:
          type: string
        endTime:
          type: string
    FlowPromptSettings:
      type: object
      properties:
        intentPrompt:
          type: string
        replyPrompt:
          type: string
        moreUserInteractionsRequired:
          type: boolean
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.