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

# Update Prompt Personas

> Adds, replaces or removes the personas a project's prompts are asked as, as the Prompts page's bulk persona actions do. Each prompt is asked as a persona through a prompt of its own (a persona variant); selecting a persona variant selects the prompt it was created from.

- `add` also asks each prompt as the listed personas.
- `replace` asks each prompt as exactly the listed personas, deleting its variants asked as any other.
- `remove` stops asking each prompt as the listed personas by deleting their variants.

Deleted variants and their history leave every report. Personas are UUIDs or names (names are case-insensitive) of the project's personas. Every variant added counts towards the prompt limit and credits (`replace` counts only those beyond the ones it deletes), so when they don't fit the request is refused with a `422` on `prompts` and nothing changes. Only active prompts can be asked as personas.



## OpenAPI

````yaml /openapi.json patch /api/v1/projects/{project}/prompts/personas
openapi: 3.1.0
info:
  title: Surfacd Public API
  version: 1.0.0
  description: >-
    Public API for Surfacd. Team-scoped operations live under
    `/api/v1/team/...`; project collections live under `/api/v1/projects`;
    project-scoped operations live under `/api/v1/projects/{project}/...`. All
    endpoints require a Bearer team API key created in Team Settings. The API
    key selects the team for team-level and collection endpoints. Reports
    default to currently monitored, nondeprecated platforms. Explicit platform
    filters can include deprecated or no-longer-monitored platforms with project
    history, provided they remain enabled globally. Admin-disabled platforms are
    excluded; no eligible default platforms means no default answers. Use
    `copilot` for historical standalone Copilot data and `bing_ai_mode` for Bing
    AI Mode; these are separate platforms. Deprecated platforms are not
    available for new monitoring through `/api/v1/platforms`.
servers:
  - url: https://app.surfacd.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Projects
    description: Project management endpoints.
  - name: Prompts
    description: Prompt management endpoints.
  - name: Team
    description: Team settings and plan details for the current team.
  - name: Reporting
    description: >-
      Read-only reporting endpoints for projects (brand rankings, mentions,
      visibility, matrix analysis, source data) and single AI answers.
  - name: Reference
    description: Reference data used by create, update, and reporting filters.
  - name: Tags
    description: Project tag management endpoints.
  - name: Reputation
    description: >-
      Read-only reputation analytics for a project: sentiment overview and
      trends, themes, narratives, the AI responses behind them, and the sources
      those responses cite. Requires the Reputation capability on the project's
      team; without it these endpoints return `403`.
  - name: Reports
    description: >-
      The report query endpoint. One `POST` per report entity (`visibility`,
      `sources`, `narratives`) takes dimensions, measures, filters, an optional
      compare window and paging, and returns a dataset any renderer can draw.
      The schema and values endpoints describe what a query accepts. See the
      Reports API guide in the docs for worked examples of every app report.
  - name: Personas
    description: >-
      Project persona management endpoints. A persona is a buyer you want AI to
      recommend you to; a prompt can be asked from one persona's point of view,
      and reporting can be filtered or broken down by persona. Prompts asked
      without a persona are `no_persona` ("No persona") here and in reports, and
      the Baseline in the app. Personas are in beta and available to all teams
      with API access.
paths:
  /api/v1/projects/{project}/prompts/personas:
    parameters:
      - $ref: '#/components/parameters/ProjectUuid'
    patch:
      tags:
        - Prompts
      summary: Update Prompt Personas
      description: >-
        Adds, replaces or removes the personas a project's prompts are asked as,
        as the Prompts page's bulk persona actions do. Each prompt is asked as a
        persona through a prompt of its own (a persona variant); selecting a
        persona variant selects the prompt it was created from.


        - `add` also asks each prompt as the listed personas.

        - `replace` asks each prompt as exactly the listed personas, deleting
        its variants asked as any other.

        - `remove` stops asking each prompt as the listed personas by deleting
        their variants.


        Deleted variants and their history leave every report. Personas are
        UUIDs or names (names are case-insensitive) of the project's personas.
        Every variant added counts towards the prompt limit and credits
        (`replace` counts only those beyond the ones it deletes), so when they
        don't fit the request is refused with a `422` on `prompts` and nothing
        changes. Only active prompts can be asked as personas.
      operationId: v1ProjectsPromptsUpdatePersonas
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePromptPersonasRequest'
      responses:
        '200':
          description: >-
            Every prompt of the changed prompts' families: each prompt asked
            without a persona, then its remaining persona variants. Deleted
            variants are not included.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePromptPersonasResult'
        '404':
          description: >-
            Project not found in the current team, or the team does not have
            personas.
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  parameters:
    ProjectUuid:
      name: project
      in: path
      required: true
      description: Project UUID.
      schema:
        type: string
        format: uuid
  schemas:
    UpdatePromptPersonasRequest:
      type: object
      properties:
        action:
          type: string
          enum:
            - add
            - replace
            - remove
          description: >-
            `add` the personas, `replace` the prompts' personas with exactly
            them, or `remove` them.
        prompts:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: string
            format: uuid
          description: >-
            UUIDs of the project's prompts. A persona variant stands for the
            prompt it was created from. An unknown prompt is a `422` on
            `prompts`.
        personas:
          type: array
          minItems: 1
          maxItems: 10
          items:
            type: string
            maxLength: 255
          description: >-
            Persona UUIDs or names (case-insensitive), at most the project's
            persona limit. An unknown persona is a `422` on `personas.{index}`.
      required:
        - action
        - prompts
        - personas
    UpdatePromptPersonasResult:
      type: object
      properties:
        prompts:
          type: array
          items:
            $ref: '#/components/schemas/Prompt'
      required:
        - prompts
    Prompt:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        text:
          type: string
          description: The prompt text.
        keyword:
          type:
            - string
            - 'null'
        status:
          $ref: '#/components/schemas/PromptStatus'
        search_volume:
          type:
            - integer
            - 'null'
          description: Most recent search volume for the prompt's keyword, when known.
        topic:
          oneOf:
            - $ref: '#/components/schemas/PromptTopic'
            - type: 'null'
        persona:
          oneOf:
            - $ref: '#/components/schemas/PromptPersona'
            - type: 'null'
          description: >-
            The persona the prompt is asked as, or null for a generic prompt
            (reported as `no_persona`, the Baseline in the app).
        source_prompt_uuid:
          type: string
          format: uuid
          nullable: true
          description: >-
            For a prompt asked as a persona (a persona variant), the prompt it
            was created from, whose text it shares. Null for every other prompt.
        persona_prompts:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/PersonaPromptReference'
          description: >-
            The personas a prompt without a persona is asked as: one entry per
            live persona variant, with the variant's `uuid` and its `persona`,
            ordered by persona name. Empty when the prompt is asked as no
            persona; null for a persona variant, which is asked as its own
            `persona`. Change it with `add_personas` and `remove_personas` on
            `PATCH /api/v1/projects/{project}/prompts/{prompt}`.
        buying_stage:
          $ref: '#/components/schemas/BuyingStage'
          description: >-
            The prompt's buying stage. A prompt and its persona variants always
            share one stage. A new prompt is `consideration` until it is
            classified, usually within minutes. Set it with `buying_stage` on
            `PATCH /api/v1/projects/{project}/prompts/{prompt}`.
        country:
          $ref: '#/components/schemas/ProjectCountry'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/PromptTag'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - uuid
        - text
        - keyword
        - status
        - search_volume
        - topic
        - persona
        - source_prompt_uuid
        - persona_prompts
        - buying_stage
        - country
        - tags
        - created_at
        - updated_at
    ValidationError:
      type: object
      description: Returned when one or more request parameters fail validation.
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      required:
        - message
        - errors
    PromptStatus:
      type: string
      enum:
        - suggestion
        - declined
        - inactive
        - active
    PromptTopic:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        name:
          type: string
      required:
        - uuid
        - name
    PromptPersona:
      type: object
      description: >-
        Compact reference to the persona a prompt is asked as. Fetch the full
        persona with `GET /api/v1/projects/{project}/personas/{persona}`.
      properties:
        uuid:
          type: string
          format: uuid
        name:
          type: string
      required:
        - uuid
        - name
    PersonaPromptReference:
      type: object
      description: >-
        A persona a prompt is asked as: the persona variant that asks it (fetch
        it with `GET /api/v1/projects/{project}/prompts/{prompt}`) and its
        persona.
      properties:
        uuid:
          type: string
          format: uuid
          description: The persona variant's UUID.
        persona:
          $ref: '#/components/schemas/PromptPersona'
      required:
        - uuid
        - persona
    BuyingStage:
      type: string
      enum:
        - awareness
        - consideration
        - decision
      description: >-
        Where in the buying journey the person asking is: `awareness` (learning
        about a problem or topic), `consideration` (comparing ways to solve it)
        or `decision` (choosing who to buy from).
    ProjectCountry:
      type: object
      properties:
        code:
          type: string
          description: ISO 3166-1 alpha-2 country code (lowercase).
        name:
          type: string
      required:
        - code
        - name
    PromptTag:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        name:
          type: string
        color:
          type:
            - string
            - 'null'
          enum:
            - gray
            - blue
            - cyan
            - purple
            - pink
            - red
            - orange
            - yellow
            - green
            - teal
            - null
          description: >-
            Tag chip colour palette name. Allowed values: gray, blue, cyan,
            purple, pink, red, orange, yellow, green, teal. Null or omitted
            displays as gray in the UI. Hex colours are not accepted.
      required:
        - uuid
        - name
        - color
  responses:
    ValidationError:
      description: Validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: >-
        Team API key created in Team Settings. Use it with URLs for the same
        team.

````

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