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

# Search Research

> Use Gemini only for candidate selection, then return canonical stored JSON.



## OpenAPI

````yaml /api-reference/openapi.json post /api/public/v1/research/search/
openapi: 3.1.0
info:
  title: User Intuition Public API
  description: >-
    ## Public Integration API


    Programmatic access to User Intuition for external integrators: manage
    studies, participants, interviews, reports, and panels.


    ### Authentication


    All endpoints require a Bearer token — either an API key (prefixed `ui_sk_`,
    created in the dashboard) or a dashboard JWT:


    ```

    Authorization: Bearer <ui_sk_… or JWT>

    ```


    ### Base URLs


    - **Production:** `https://api.userintuition.ai`

    - **Staging:** `https://staging.userintuition.ai`


    ### Support


    For API support, contact support@userintuition.ai
  version: 1.0.0
  contact:
    name: User Intuition Support
    email: support@userintuition.ai
servers:
  - url: https://api.userintuition.ai
    description: Production
  - url: https://staging.userintuition.ai
    description: Staging
security:
  - BearerAuth: []
paths:
  /api/public/v1/research/search/:
    post:
      tags:
        - public-research-search
      summary: Search Research
      description: >-
        Use Gemini only for candidate selection, then return canonical stored
        JSON.
      operationId: searchResearch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicResearchSearchRequest'
            examples:
              Find pricing evidence:
                summary: Find pricing evidence
                description: >-
                  Search one indexed study and return canonical finding/response
                  JSON; cursor must be null in this release.
                value:
                  query: What makes people think The Ribbon is too expensive?
                  filters:
                    study_ids:
                      - 11111111-2222-3333-4444-555555555555
                    content_types:
                      - study_finding
                      - participant_response
                    research_date_from: '2026-01-01'
                    research_date_to: '2026-09-16'
                  limit: 10
                  cursor: null
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicResearchSearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PublicResearchSearchRequest:
      properties:
        query:
          type: string
          maxLength: 2000
          minLength: 1
          title: Query
        filters:
          $ref: '#/components/schemas/PublicResearchSearchFilters'
        limit:
          type: integer
          maximum: 50
          minimum: 1
          title: Limit
          default: 10
        cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Cursor
          description: Reserved for future pagination. The first release accepts only null.
      type: object
      required:
        - query
        - filters
      title: PublicResearchSearchRequest
    PublicResearchSearchResponse:
      properties:
        studies:
          items:
            $ref: '#/components/schemas/PublicResearchStudyResults'
          type: array
          title: Studies
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
        generated_content_returned:
          type: boolean
          const: false
          title: Generated Content Returned
          default: false
      type: object
      title: PublicResearchSearchResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PublicResearchSearchFilters:
      properties:
        study_ids:
          items:
            type: string
          type: array
          maxItems: 20
          minItems: 1
          title: Study Ids
        content_types:
          anyOf:
            - items:
                type: string
                enum:
                  - study_plan
                  - study_finding
                  - participant_profile
                  - participant_response
                  - recommended_next_step
              type: array
            - type: 'null'
          title: Content Types
        research_date_from:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Research Date From
        research_date_to:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Research Date To
      type: object
      required:
        - study_ids
      title: PublicResearchSearchFilters
    PublicResearchStudyResults:
      properties:
        study_id:
          type: string
          title: Study Id
        index_status:
          type: string
          enum:
            - ready
            - updating
            - not_indexed
          title: Index Status
        latest_report_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Latest Report Id
        indexed_report_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Indexed Report Id
        results:
          items:
            anyOf:
              - $ref: '#/components/schemas/PublicStudyPlanSearchResult'
              - $ref: '#/components/schemas/PublicStudyFindingSearchResult'
              - $ref: '#/components/schemas/PublicParticipantProfileSearchResult'
              - $ref: '#/components/schemas/PublicParticipantResponseSearchResult'
              - $ref: '#/components/schemas/PublicRecommendedNextStepSearchResult'
          type: array
          title: Results
      type: object
      required:
        - study_id
        - index_status
      title: PublicResearchStudyResults
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    PublicStudyPlanSearchResult:
      properties:
        content_id:
          type: string
          title: Content Id
        report_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Report Id
        research_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Research Date
        content_type:
          type: string
          const: study_plan
          title: Content Type
        content:
          $ref: '#/components/schemas/PublicStudyPlan'
      type: object
      required:
        - content_id
        - content_type
        - content
      title: PublicStudyPlanSearchResult
    PublicStudyFindingSearchResult:
      properties:
        content_id:
          type: string
          title: Content Id
        report_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Report Id
        research_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Research Date
        content_type:
          type: string
          const: study_finding
          title: Content Type
        content:
          $ref: '#/components/schemas/PublicReportSection'
      type: object
      required:
        - content_id
        - content_type
        - content
      title: PublicStudyFindingSearchResult
    PublicParticipantProfileSearchResult:
      properties:
        content_id:
          type: string
          title: Content Id
        report_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Report Id
        research_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Research Date
        content_type:
          type: string
          const: participant_profile
          title: Content Type
        content:
          $ref: '#/components/schemas/PublicParticipantProfileSection'
      type: object
      required:
        - content_id
        - content_type
        - content
      title: PublicParticipantProfileSearchResult
    PublicParticipantResponseSearchResult:
      properties:
        content_id:
          type: string
          title: Content Id
        report_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Report Id
        research_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Research Date
        content_type:
          type: string
          const: participant_response
          title: Content Type
        content:
          $ref: '#/components/schemas/PublicParticipantResponse'
      type: object
      required:
        - content_id
        - content_type
        - content
      title: PublicParticipantResponseSearchResult
    PublicRecommendedNextStepSearchResult:
      properties:
        content_id:
          type: string
          title: Content Id
        report_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Report Id
        research_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Research Date
        content_type:
          type: string
          const: recommended_next_step
          title: Content Type
        content:
          $ref: '#/components/schemas/PublicRecommendedNextStep'
      type: object
      required:
        - content_id
        - content_type
        - content
      title: PublicRecommendedNextStepSearchResult
    PublicStudyPlan:
      properties:
        objectives:
          type: string
          title: Objectives
          description: What the study is trying to learn and the decision it informs.
        conversation_flow:
          type: string
          title: Conversation Flow
          description: >-
            How the interview should flow — topics/clusters with example
            prompts.
        background:
          anyOf:
            - type: string
            - type: 'null'
          title: Background
          description: Context about the company/product/market.
        learning_goals:
          anyOf:
            - type: string
            - type: 'null'
          title: Learning Goals
          description: The critical things to learn (bullets).
        key_questions:
          anyOf:
            - type: string
            - type: 'null'
          title: Key Questions
          description: The specific questions to answer (bullets).
        study_specific_rules:
          anyOf:
            - type: string
            - type: 'null'
          title: Study Specific Rules
          description: Operational guardrails and neutrality notes.
        study_improvements:
          anyOf:
            - type: string
            - type: 'null'
          title: Study Improvements
          description: Accepted additions to guide future interviews.
      additionalProperties: false
      type: object
      required:
        - objectives
        - conversation_flow
      title: PublicStudyPlan
      description: |-
        The interview instructions, as named sections. ``objectives`` and
        ``conversation_flow`` are required; the rest are optional. Each value is
        free-form text/markdown (bullets allowed).
    PublicReportSection:
      properties:
        heading:
          type: string
          title: Heading
        level:
          type: integer
          maximum: 6
          minimum: 1
          title: Level
        content:
          type: string
          title: Content
          default: ''
        markdown:
          type: string
          title: Markdown
          default: ''
        order:
          type: integer
          minimum: 0
          title: Order
        reference_ids:
          items:
            type: string
          type: array
          title: Reference Ids
          description: Citation IDs that resolve through the report's references array
        children:
          additionalProperties:
            $ref: '#/components/schemas/PublicReportSection'
          type: object
          title: Children
          description: Subsections keyed by their stable heading attribute
      type: object
      required:
        - heading
        - level
        - order
      title: PublicReportSection
    PublicParticipantProfileSection:
      properties:
        heading:
          type: string
          title: Heading
        level:
          type: integer
          maximum: 6
          minimum: 1
          title: Level
        content:
          items:
            $ref: '#/components/schemas/PublicParticipantProfileAnswer'
          type: array
          title: Content
        markdown:
          type: string
          title: Markdown
          default: ''
        order:
          type: integer
          minimum: 0
          title: Order
        reference_ids:
          items:
            type: string
          type: array
          title: Reference Ids
      type: object
      required:
        - heading
        - level
        - order
      title: PublicParticipantProfileSection
    PublicParticipantResponse:
      properties:
        call_id:
          type: string
          title: Call Id
          description: Provider call ID
        interview_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Interview Id
          description: Public interview record ID
        overall_takeaways:
          items:
            type: string
          type: array
          title: Overall Takeaways
        key_questions:
          items:
            $ref: '#/components/schemas/PublicParticipantKeyQuestion'
          type: array
          title: Key Questions
      type: object
      required:
        - call_id
      title: PublicParticipantResponse
    PublicRecommendedNextStep:
      properties:
        action:
          type: string
          title: Action
        study_slug:
          anyOf:
            - type: string
            - type: 'null'
          title: Study Slug
        title:
          type: string
          title: Title
        rationale:
          type: string
          title: Rationale
        context:
          anyOf:
            - type: string
            - type: 'null'
          title: Context
      type: object
      required:
        - action
        - title
        - rationale
      title: PublicRecommendedNextStep
    PublicParticipantProfileAnswer:
      properties:
        answer:
          type: string
          title: Answer
        participants:
          type: integer
          minimum: 0
          title: Participants
        percentage:
          type: integer
          maximum: 100
          minimum: 0
          title: Percentage
      type: object
      required:
        - answer
        - participants
        - percentage
      title: PublicParticipantProfileAnswer
    PublicParticipantKeyQuestion:
      properties:
        call_id:
          type: string
          title: Call Id
        kq_index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Kq Index
        kq_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Kq Text
        explored:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Explored
        answered:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Answered
        summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Summary
        quote:
          anyOf:
            - type: string
            - type: 'null'
          title: Quote
      type: object
      required:
        - call_id
      title: PublicParticipantKeyQuestion
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Authenticate with an API key (prefixed `ui_sk_`) or a JWT token from the
        dashboard.

````