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

# Get Answer

> One AI answer in full, on every plan: the prompt it answers (with its target country), the platform, when it was collected (`prompt_response.checked_at`), the full answer text, every tracked brand it names with its position (`rank`) and sentiment, the pages it cites and the web searches the platform ran. List answers with `POST /api/v1/projects/{project}/reports/visibility` and `answer` in `dimensions`, then pass a row's `answer_uuid` here.

With Reputation on for the project the answer also lists the narratives it carries in `narratives`; without it the key is left out, and the request still succeeds. This endpoint replaces `GET /api/v1/projects/{project}/reputation/responses/{response}`: the fields are the same, plus `narratives`.



## OpenAPI

````yaml /openapi.json get /api/v1/projects/{project}/responses/{response}
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}/responses/{response}:
    parameters:
      - $ref: '#/components/parameters/ProjectUuid'
      - $ref: '#/components/parameters/ResponseUuid'
    get:
      tags:
        - Reporting
      summary: Get Answer
      description: >-
        One AI answer in full, on every plan: the prompt it answers (with its
        target country), the platform, when it was collected
        (`prompt_response.checked_at`), the full answer text, every tracked
        brand it names with its position (`rank`) and sentiment, the pages it
        cites and the web searches the platform ran. List answers with `POST
        /api/v1/projects/{project}/reports/visibility` and `answer` in
        `dimensions`, then pass a row's `answer_uuid` here.


        With Reputation on for the project the answer also lists the narratives
        it carries in `narratives`; without it the key is left out, and the
        request still succeeds. This endpoint replaces `GET
        /api/v1/projects/{project}/reputation/responses/{response}`: the fields
        are the same, plus `narratives`.
      operationId: v1ProjectsResponsesShow
      responses:
        '200':
          description: The answer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnswerDetail'
        '404':
          description: >-
            Answer not found in this project, or the project is not in the API
            key's team.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
components:
  parameters:
    ProjectUuid:
      name: project
      in: path
      required: true
      description: Project UUID.
      schema:
        type: string
        format: uuid
    ResponseUuid:
      name: response
      in: path
      required: true
      description: >-
        The AI response UUID. Scoped to the project's responses; a foreign UUID
        returns 404.
      schema:
        type: string
        format: uuid
  schemas:
    AnswerDetail:
      type: object
      description: >-
        One AI answer in full: the answer record, its prompt (with target
        country), the platform, the pages it cites, the brands it names, the
        searches the platform ran and, with Reputation, the narratives it
        carries.
      properties:
        prompt_response:
          $ref: '#/components/schemas/ReputationResponsePromptResponse'
          description: >-
            The answer record: its `uuid`, the full `response_text` and
            `checked_at`, when it was collected.
        prompt:
          $ref: '#/components/schemas/ReputationResponsePrompt'
          description: >-
            The prompt the answer responds to: its `uuid`, `prompt_text` and
            target `country`.
        service:
          $ref: '#/components/schemas/ReputationResponseService'
          description: The AI platform that gave the answer.
        sources:
          type: array
          items:
            $ref: '#/components/schemas/ReputationResponseSource'
          description: >-
            The pages the answer cites, with `url`, `domain` and the page's
            recorded `title` (null when none was recorded).
        brand_mentions:
          type: array
          items:
            $ref: '#/components/schemas/AnswerBrandMention'
          description: Every tracked brand the answer names, first named first.
        fan_out_queries:
          type: array
          items:
            $ref: '#/components/schemas/FanOutQuery'
          description: >-
            The web searches the platform ran before answering (`kind`
            `search`), then any follow-up questions it suggested (`kind`
            `related`). Empty for platforms that answer from knowledge alone.
        narratives:
          type: array
          items:
            $ref: '#/components/schemas/AnswerNarrative'
          description: >-
            Present only when Reputation is on for the project: the team's plan
            includes it and the project has enabled it. Left out otherwise. One
            entry per passage, the narrative more of the project's answers carry
            for that brand first; one narrative's passages stay together. Empty
            when the answer carries none.
      required:
        - prompt_response
        - prompt
        - service
        - sources
        - brand_mentions
        - fan_out_queries
    ReputationResponsePromptResponse:
      type: object
      description: The raw AI response record behind a reputation mention.
      properties:
        uuid:
          type: string
          format: uuid
        response_text:
          type: string
        response_metadata:
          type:
            - object
            - 'null'
        checked_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        prompt:
          oneOf:
            - $ref: '#/components/schemas/ReputationResponsePrompt'
            - type: 'null'
        service:
          oneOf:
            - $ref: '#/components/schemas/ReputationResponseService'
            - type: 'null'
      required:
        - uuid
        - response_text
        - checked_at
        - created_at
        - updated_at
    ReputationResponsePrompt:
      type: object
      description: The prompt behind a reputation response, with its target country.
      properties:
        uuid:
          type: string
          format: uuid
        keyword:
          type:
            - string
            - 'null'
        prompt_text:
          type: string
        search_volume:
          type:
            - integer
            - 'null'
        status:
          type: integer
          description: >-
            Prompt status: `0` Suggestion, `1` Declined, `2` Inactive, `3`
            Active.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        deleted_at:
          type:
            - string
            - 'null'
          format: date-time
        brand_visibility:
          type:
            - number
            - 'null'
          format: float
        search_volume_level:
          type:
            - integer
            - 'null'
        is_volume_hydrated:
          type: boolean
        project:
          type: 'null'
        topic:
          type:
            - object
            - 'null'
        persona:
          oneOf:
            - $ref: '#/components/schemas/ReputationResponsePersona'
            - type: 'null'
          description: The persona the prompt is asked as, or null for a generic prompt.
        country:
          oneOf:
            - $ref: '#/components/schemas/ReputationResponseCountry'
            - type: 'null'
        tags:
          type:
            - array
            - 'null'
          items:
            type: object
      required:
        - uuid
        - prompt_text
        - status
        - created_at
        - updated_at
        - is_volume_hydrated
    ReputationResponseService:
      type: object
      description: The AI platform that produced a reputation response.
      properties:
        uuid:
          type: string
          format: uuid
        provider:
          type: string
        name:
          type: string
        display_name:
          type: string
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - uuid
        - provider
        - name
        - display_name
        - is_active
        - created_at
        - updated_at
    ReputationResponseSource:
      type: object
      description: A source URL cited by an AI response.
      properties:
        url:
          type: string
        domain:
          type: string
        hostname:
          type: string
        title:
          type:
            - string
            - 'null'
        category:
          type:
            - string
            - 'null'
          enum:
            - ugc
            - editorial
            - corporate
            - reference
            - academic
            - analyst
            - institutional
            - other
            - null
          description: The cited site's category, when it has been classified.
        rank:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - url
        - domain
        - hostname
        - rank
        - created_at
        - updated_at
    AnswerBrandMention:
      description: >-
        A tracked brand the answer names: where (`rank`, 1 = named first), how
        (`sentiment`) and which brand.
      allOf:
        - $ref: '#/components/schemas/BrandMention'
        - type: object
          properties:
            brand:
              type: object
              description: The brand named.
              properties:
                uuid:
                  type: string
                  format: uuid
                name:
                  type: string
                domain:
                  type:
                    - string
                    - 'null'
                type:
                  $ref: '#/components/schemas/BrandType'
                brand_aliases:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                created_at:
                  type: string
                  format: date-time
                updated_at:
                  type: string
                  format: date-time
                deleted_at:
                  type:
                    - string
                    - 'null'
                  format: date-time
              required:
                - uuid
                - name
                - domain
                - type
                - created_at
                - updated_at
            prompt_response:
              type: 'null'
              description: Not loaded here; the answer is the enclosing object.
            prompt:
              type: 'null'
              description: Not loaded here; see the answer's `prompt`.
            service:
              type: 'null'
              description: Not loaded here; see the answer's `service`.
            other_brand_mentions:
              type: 'null'
              description: Not loaded here; see the answer's `brand_mentions`.
          required:
            - brand
    FanOutQuery:
      type: object
      description: >-
        One web search the AI platform ran while building the answer, or with
        `kind` `related`, a follow-up question it suggested under the answer and
        never searched. Searches first, each kind in the order the platform gave
        them.
      properties:
        query:
          type: string
          description: >-
            The search text as issued, including any operators such as site: or
            quoted phrases.
        rank:
          type: integer
          description: >-
            1-based position in the order the platform gave them, within its
            kind.
        kind:
          type: string
          enum:
            - search
            - related
          description: >-
            `search`: a web search the platform ran. `related`: a follow-up
            question it suggested.
      required:
        - query
        - rank
        - kind
    AnswerNarrative:
      type: object
      description: >-
        One narrative the answer carries for one brand, with the passage it was
        read from.
      properties:
        brand_uuid:
          type: string
          format: uuid
          description: The brand the passage is about.
        narrative_uuid:
          type: string
          format: uuid
        narrative:
          type: string
          description: The narrative's label.
        theme_uuid:
          type:
            - string
            - 'null'
          format: uuid
          description: The narrative's theme, null when it has none.
        theme:
          type:
            - string
            - 'null'
          description: The theme's label, null when the narrative has no theme.
        sentiment:
          $ref: '#/components/schemas/BrandSentiment'
        snippet:
          type:
            - string
            - 'null'
          description: >-
            The passage the narrative was read from, null when none was
            recorded.
      required:
        - brand_uuid
        - narrative_uuid
        - narrative
        - theme_uuid
        - theme
        - sentiment
        - snippet
    ReputationResponsePersona:
      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
        job_titles:
          type: array
          items:
            type: string
      required:
        - uuid
        - name
        - job_titles
    ReputationResponseCountry:
      type: object
      description: The target country of the prompt behind a reputation response.
      properties:
        code:
          type: string
        name:
          type: string
        is_active:
          type: boolean
        primary_language:
          type:
            - string
            - 'null'
        flag:
          type: string
      required:
        - code
        - name
        - is_active
        - flag
    BrandMention:
      type: object
      description: >-
        Public brand mention representation. Internal numeric IDs are not
        exposed; nested related objects use public UUIDs or provider/country
        identifiers where present.
      properties:
        sentiment:
          type: string
          description: '`positive`, `negative`, or `neutral`.'
        salience_score:
          type: string
          description: Returned as a string for precision; parse to float on the client.
        rank:
          type: integer
        mention_snippet:
          type:
            - string
            - 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - sentiment
        - salience_score
        - rank
        - mention_snippet
        - created_at
        - updated_at
    BrandType:
      type: integer
      enum:
        - 0
        - 1
        - 2
      description: >-
        `0` = Standard, `1` = Primary (the project's own brand), `2` =
        Competitor.
    BrandSentiment:
      type: string
      enum:
        - positive
        - negative
        - neutral
      description: The sentiment valence of a mention or narrative.
  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.