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

# Customize Study Plan

> Run one resumable turn through the same planning agent and tools used by
the dashboard's Customize Plan page.

The conversation id is stored on the study. Questions are returned to the
caller; completed plan markdown is persisted automatically.



## OpenAPI

````yaml /api-reference/openapi.json post /api/public/v1/studies/{study_id}/customize-plan
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/studies/{study_id}/customize-plan:
    post:
      tags:
        - public-studies
      summary: Customize Study Plan
      description: >-
        Run one resumable turn through the same planning agent and tools used by

        the dashboard's Customize Plan page.


        The conversation id is stored on the study. Questions are returned to
        the

        caller; completed plan markdown is persisted automatically.
      operationId: customizeStudyPlan
      parameters:
        - name: study_id
          in: path
          required: true
          schema:
            type: string
            title: Study Id
          example: 11111111-2222-3333-4444-555555555555
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Idempotency-Key
        - name: X-UI-Organization-ID
          in: header
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 128
              - type: 'null'
            description: >-
              Platform admins only: choose an organization for scoped reads and
              writes. Required to change another organization's study or use its
              wallet.
            title: X-Ui-Organization-Id
          description: >-
            Platform admins only: choose an organization for scoped reads and
            writes. Required to change another organization's study or use its
            wallet.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicCustomizeStudyRequest'
            examples:
              Planning turn:
                summary: Planning instruction
                description: >-
                  Send one natural-language turn. If response_type is question,
                  answer it in the next call.
                value:
                  message: >-
                    We want to understand how households choose a blender or
                    microwave. Ask about one recent purchase, what triggered it,
                    the closest alternative, and how they weighed price against
                    reliability.
              Delegated research design:
                summary: Proceed with research-design assumptions
                description: >-
                  The researcher delegated ordinary design choices. Keep
                  draft-only workflow instructions out of the research message;
                  this call does not launch fieldwork.
                value:
                  message: >-
                    Understand why recent buyers abandoned checkout and what
                    reassurance they needed.
                  decisions: agent
                  execution_policy: draft_only
              Concept image:
                summary: Planning turn with concept image
                description: >-
                  data_base64 contains image bytes only, without a data-URL
                  prefix. Decoded files may be at most 10 MB.
                value:
                  message: >-
                    Add this checkout screen to the plan and ask what the
                    participant expects to happen next.
                  concept_image:
                    data_base64: iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB
                    filename: checkout.png
                    content_type: image/png
                    label: Checkout screen
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicCustomizeStudyResponse'
        '422':
          description: Public API error. X-Request-ID matches error.request_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
        default:
          description: Public API error. X-Request-ID matches error.request_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorResponse'
components:
  schemas:
    PublicCustomizeStudyRequest:
      properties:
        message:
          type: string
          maxLength: 20000
          minLength: 1
          title: Message
        decisions:
          type: string
          enum:
            - human
            - agent
          title: Decisions
          description: >-
            human relays required decisions; agent makes reviewable assumptions
            when possible.
          default: human
        execution_policy:
          type: string
          enum:
            - review_before_fieldwork
            - draft_only
          title: Execution Policy
          description: >-
            Caller workflow constraint, kept separate from participant-facing
            research content. This endpoint never launches recruitment.
          default: review_before_fieldwork
        concept_image:
          anyOf:
            - $ref: '#/components/schemas/PublicCustomizeConceptImage'
            - type: 'null'
          description: >-
            Optional native concept-image attachment for this turn. The backend
            validates, stores, and makes it available to Customize Plan.
      additionalProperties: false
      type: object
      required:
        - message
      title: PublicCustomizeStudyRequest
      description: One user turn for the stateful Customize Plan conversation.
    PublicCustomizeStudyResponse:
      properties:
        message:
          type: string
          title: Message
        response_type:
          type: string
          enum:
            - question
            - message
            - study_plan
          title: Response Type
        questions:
          items:
            $ref: '#/components/schemas/PublicPlanningQuestion'
          type: array
          title: Questions
        assumptions:
          items:
            type: string
          type: array
          title: Assumptions
        execution_policy:
          type: string
          enum:
            - review_before_fieldwork
            - draft_only
          title: Execution Policy
          default: review_before_fieldwork
        study:
          $ref: '#/components/schemas/PublicStudySummary'
      type: object
      required:
        - message
        - response_type
        - study
      title: PublicCustomizeStudyResponse
      description: The next Customize Plan message plus the study's resulting state.
    PublicApiErrorResponse:
      type: object
      required:
        - detail
        - error
      properties:
        detail:
          description: Legacy error detail; may be a string, list, or object.
        error:
          $ref: '#/components/schemas/PublicApiError'
    PublicCustomizeConceptImage:
      properties:
        data_base64:
          type: string
          maxLength: 14000000
          minLength: 1
          title: Data Base64
          description: 'Base64-encoded image bytes (maximum decoded size: 10 MB).'
        filename:
          type: string
          maxLength: 255
          minLength: 1
          title: Filename
        content_type:
          type: string
          enum:
            - image/png
            - image/jpeg
            - image/gif
            - image/webp
          title: Content Type
        label:
          type: string
          maxLength: 120
          minLength: 1
          title: Label
          description: User-approved participant-facing label.
      additionalProperties: false
      type: object
      required:
        - data_base64
        - filename
        - content_type
        - label
      title: PublicCustomizeConceptImage
      description: A client-provided image attached to a Customize Plan turn.
    PublicPlanningQuestion:
      properties:
        id:
          type: string
          title: Id
        text:
          type: string
          title: Text
        options:
          items:
            type: string
          type: array
          title: Options
        default:
          anyOf:
            - type: string
            - type: 'null'
          title: Default
      type: object
      required:
        - id
        - text
      title: PublicPlanningQuestion
    PublicStudySummary:
      properties:
        id:
          type: string
          title: Id
        name:
          anyOf:
            - type: string
              maxLength: 40
            - type: 'null'
          title: Name
        study_type:
          type: string
          enum:
            - in-depth-interview
            - concept-test
            - prototype-test
          title: Study Type
          description: Current study-type template slug
        use_case:
          anyOf:
            - type: string
            - type: 'null'
          title: Use Case
          description: Historical study-type label when it is outside the current catalog
        recruiting_method:
          anyOf:
            - type: string
              enum:
                - panel
                - byop
                - synthetic_respondents
            - type: 'null'
          enum:
            - panel
            - byop
            - synthetic_respondents
          title: Recruiting Method
          description: panel, byop, or synthetic_respondents
        interview_format:
          anyOf:
            - type: string
              enum:
                - chat
                - video
                - voice
            - type: 'null'
          title: Interview Format
          description: chat, video, or voice
        voice:
          anyOf:
            - type: string
              enum:
                - male
                - female
            - type: 'null'
          title: Voice
          description: male or female
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
          description: Interview language code, e.g. 'en'
        expected_duration_seconds:
          type: integer
          minimum: 300
          title: Expected Duration Seconds
          description: >-
            Maximum planned interview duration in seconds, including transitions
            and likely follow-up probes. This is an estimate, not a guaranteed
            length.
          default: 900
        byop_config:
          $ref: '#/components/schemas/PublicByopConfigOut'
        study_link:
          anyOf:
            - type: string
            - type: 'null'
          title: Study Link
          description: >-
            Live participant interview link; null until the interviewer is
            provisioned. This is not a researcher preview URL.
        dashboard_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Dashboard Url
          description: Researcher management link for the study
        provisioning_status:
          type: string
          enum:
            - draft
            - ready
            - provisioned
          title: Provisioning Status
          description: >-
            draft when required interviewer settings are missing, ready when the
            study can be provisioned, and provisioned when interviews can run
        fielding_status:
          type: string
          enum:
            - not_started
            - starting
            - collecting
            - fielding
            - paused
            - complete
            - partial
            - failed
            - stopped
            - unavailable
            - not_applicable
            - unknown
          title: Fielding Status
          description: >-
            Recruitment state, separate from interviewer provisioning. Panel
            studies report their persisted lifecycle. BYOP studies are
            collecting once the interviewer is provisioned, and can be paused or
            stopped; invitation delivery is tracked per participant. Synthetic
            respondents are not_applicable.
        missing_requirements:
          items:
            type: string
          type: array
          title: Missing Requirements
          description: Fields still required before the study can be provisioned
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
        interview_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Interview Count
          description: >-
            Completed visible non-test interviews satisfying quality criteria,
            matching list_interviews(status=completed).
        report_status:
          anyOf:
            - type: string
              enum:
                - available
                - not_generated
            - type: 'null'
          title: Report Status
      type: object
      required:
        - id
        - study_type
        - provisioning_status
        - fielding_status
      title: PublicStudySummary
      description: |-
        Lightweight study shape returned by the list endpoint (heavy fields such
        as the study plan and screener questions are stripped — fetch by id).
    PublicApiError:
      type: object
      required:
        - code
        - message
        - field
        - request_id
        - outcome
        - recovery_action
        - docs_url
      properties:
        code:
          type: string
        message:
          type: string
        field:
          anyOf:
            - type: string
            - type: 'null'
        request_id:
          type: string
          format: uuid
        outcome:
          type: string
          enum:
            - not_started
            - failed
            - unknown
        recovery_action:
          type: string
        docs_url:
          type: string
          format: uri
    PublicByopConfigOut:
      properties:
        incentive_amount:
          anyOf:
            - type: number
            - type: 'null'
          title: Incentive Amount
        is_incentives_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Incentives Enabled
        auto_send_incentives:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Auto Send Incentives
      type: object
      title: PublicByopConfigOut
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authenticate with an API key (prefixed `ui_sk_`) or a JWT token from the
        dashboard.

````

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