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

# Create a new component



## OpenAPI

````yaml /openapi-components.json post /api/v1/components
openapi: 3.0.0
info:
  title: StudyFetch API
  description: API documentation for StudyFetch
  version: '1.0'
  contact: {}
servers:
  - url: https://studyfetchapi.com
    description: Production API Server
security: []
tags: []
paths:
  /api/v1/components:
    post:
      tags:
        - Components
      summary: Create a new component
      operationId: create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateComponentDto'
      responses:
        '201':
          description: Component created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentResponseDto'
      security:
        - x-api-key: []
components:
  schemas:
    CreateComponentDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - chat
            - data_analyst
            - flashcards
            - scenarios
            - practice_test
            - audio_recap
            - tutor_me
            - explainers
            - uploads
            - chat_analytics
          description: Type of component to create
        name:
          type: string
          example: My Study Component
          description: Name of the component
        description:
          type: string
          example: A component for studying biology
          description: Component description
        config:
          description: Component-specific configuration
          oneOf:
            - $ref: '#/components/schemas/ChatConfigDto'
            - $ref: '#/components/schemas/DataAnalystConfigDto'
            - $ref: '#/components/schemas/FlashcardsConfigDto'
            - $ref: '#/components/schemas/ScenariosConfigDto'
            - $ref: '#/components/schemas/PracticeTestConfigDto'
            - $ref: '#/components/schemas/AudioRecapConfigDto'
            - $ref: '#/components/schemas/ExplainersConfigDto'
            - $ref: '#/components/schemas/UploadsConfigDto'
            - $ref: '#/components/schemas/TutorMeConfigDto'
            - $ref: '#/components/schemas/ChatAnalyticsConfigDto'
        metadata:
          type: object
          description: Additional metadata
      required:
        - type
        - name
        - config
    ComponentResponseDto:
      type: object
      properties:
        _id:
          type: string
          description: Component ID (MongoDB ObjectId)
        componentId:
          type: string
          description: Unique component identifier
        type:
          type: string
          description: Component type
          enum:
            - chat
            - data_analyst
            - flashcards
            - scenarios
            - practice_test
            - audio_recap
            - tutor_me
            - explainers
            - uploads
            - chat_analytics
        name:
          type: string
          description: Component name
        description:
          type: string
          description: Component description
        organization:
          type: string
          description: Organization ID
        config:
          type: object
          description: Component configuration
        status:
          type: string
          description: Component status
          enum:
            - active
            - inactive
            - draft
        usage:
          type: object
          description: Usage statistics
        createdAt:
          format: date-time
          type: string
          description: Creation timestamp
        updatedAt:
          format: date-time
          type: string
          description: Last update timestamp
      required:
        - _id
        - componentId
        - type
        - name
        - organization
        - config
        - status
        - usage
        - createdAt
        - updatedAt
    ChatConfigDto:
      type: object
      properties:
        materials:
          description: Material IDs
          type: array
          items:
            type: string
        folders:
          description: Folder IDs
          type: array
          items:
            type: string
        model:
          type: string
          example: gpt-4o-mini-2024-07-18
          description: AI model to use
        systemPrompt:
          type: string
          description: System prompt for the chat
        temperature:
          type: number
          minimum: 0
          maximum: 2
          description: Temperature for response generation
        maxTokens:
          type: number
          description: Maximum tokens for response
        enableWebSearch:
          type: boolean
          description: Enable web search
        enableRAGSearch:
          type: boolean
          description: Enable RAG search
        enableHistory:
          type: boolean
          description: Enable conversation history
        enableVoice:
          type: boolean
          description: Enable voice interactions
        enableFollowUps:
          type: boolean
          description: Enable follow-up questions
        enableComponentCreation:
          type: boolean
          description: Enable component creation
        maxSteps:
          type: number
          description: Maximum steps for multi-step tool calls
        enableGuardrails:
          type: boolean
          description: Enable guardrails for content moderation
        enableMessageGrading:
          type: boolean
          description: Enable message grading for prompt improvement suggestions
          default: true
        guardrailRules:
          description: Guardrail rules for content moderation
          example:
            - id: rule-1
              description: No direct homework answers
              condition: The AI response provides direct answers to homework
              action: block
              message: I cannot provide direct answers to homework questions.
          type: array
          items:
            $ref: '#/components/schemas/GuardrailRuleDto'
        enableReferenceMode:
          type: boolean
          description: Enable reference mode - show references instead of source content
      required:
        - model
    DataAnalystConfigDto:
      type: object
      properties:
        materials:
          description: Material IDs
          type: array
          items:
            type: string
        folders:
          description: Folder IDs
          type: array
          items:
            type: string
        model:
          type: string
          example: gpt-4o-mini-2024-07-18
          description: AI model to use
        systemPrompt:
          type: string
          description: System prompt for the data analyst
        temperature:
          type: number
          minimum: 0
          maximum: 2
          description: Temperature for response generation
        maxTokens:
          type: number
          description: Maximum tokens for response
        enableWebSearch:
          type: boolean
          description: Enable web search
        enableRAGSearch:
          type: boolean
          description: Enable RAG search
        enableHistory:
          type: boolean
          description: Enable conversation history
        enableVoice:
          type: boolean
          description: Enable voice interactions
        enableFollowUps:
          type: boolean
          description: Enable follow-up questions
        enableComponentCreation:
          type: boolean
          description: Enable component creation
        maxSteps:
          type: number
          description: Maximum steps for multi-step tool calls
        groupIds:
          description: Group IDs to filter data
          type: array
          items:
            type: string
      required:
        - model
    FlashcardsConfigDto:
      type: object
      properties:
        materials:
          description: Material IDs
          type: array
          items:
            type: string
        folders:
          description: Folder IDs
          type: array
          items:
            type: string
        model:
          type: string
          description: AI model to use for flashcard generation
          example: gpt-4o-mini-2024-07-18
        difficulty:
          type: string
          enum:
            - easy
            - medium
            - hard
            - mixed
          description: Difficulty level
        totalFlashcards:
          type: number
          description: Total number of flashcards to generate
        viewMode:
          type: string
          enum:
            - spaced_repetition
            - normal
          description: View mode for flashcards
        cardTypes:
          description: Types of flashcards
          type: array
          items:
            type: string
        maxReviewInterval:
          type: number
          description: Maximum review interval in days
        learningSteps:
          type: string
          description: Learning steps configuration
    ScenariosConfigDto:
      type: object
      properties:
        materials:
          description: Material IDs
          type: array
          items:
            type: string
        folders:
          description: Folder IDs
          type: array
          items:
            type: string
        model:
          type: string
          description: AI model to use for scenario generation
          example: gpt-4o-mini-2024-07-18
        context:
          type: string
          description: Scenario context
        goal:
          type: string
          description: Scenario goal
        format:
          type: string
          description: Scenario format
        greetingMessage:
          type: string
          description: Greeting message
        greetingCharacterId:
          type: string
          description: Character ID for greeting
        requiresFinalAnswer:
          type: boolean
          description: Requires final answer
        finalAnswerPrompt:
          type: string
          description: Final answer prompt
        characters:
          description: Scenario characters
          type: array
          items:
            $ref: '#/components/schemas/CharacterDto'
        tools:
          description: Available tools
          type: array
          items:
            $ref: '#/components/schemas/ToolDto'
        criteria:
          description: >-
            Authored evaluation criteria. If omitted or empty at create time,
            the AI will generate criteria.
          type: array
          items:
            $ref: '#/components/schemas/EvaluationCriterionDto'
        enableHistory:
          type: boolean
          description: Enable history
        enableVoice:
          type: boolean
          description: Enable voice
        placeholderText:
          type: string
          description: Placeholder text
    PracticeTestConfigDto:
      type: object
      properties:
        materials:
          description: Material IDs
          type: array
          items:
            type: string
        folders:
          description: Folder IDs
          type: array
          items:
            type: string
        model:
          type: string
          description: AI model to use for question generation and grading
          example: gpt-4o-mini-2024-07-18
        questionTypes:
          description: Question types
          example:
            - multiplechoice
            - truefalse
          type: array
          items:
            type: string
        questionsPerTest:
          type: number
          description: Number of questions per test
        difficulty:
          type: string
          enum:
            - easy
            - medium
            - hard
            - mixed
          description: Difficulty level
        timeLimit:
          type: number
          description: Time limit in minutes
        allowRetakes:
          type: boolean
          description: Allow retakes
        showCorrectAnswers:
          type: boolean
          description: Show correct answers after submission
        randomizeQuestions:
          type: boolean
          description: Randomize question order
        randomizeAnswers:
          type: boolean
          description: Randomize answer order
        maxAttempts:
          type: number
          description: Maximum attempts allowed
        passingScore:
          type: number
          description: Passing score percentage
        showExplanations:
          type: boolean
          description: Show explanations for answers
        aiGenerationMode:
          type: string
          enum:
            - balanced
            - comprehensive
            - focused
            - adaptive
          description: AI generation mode
        questionDistribution:
          description: Distribution of question types
          allOf:
            - $ref: '#/components/schemas/QuestionDistributionDto'
      required:
        - questionTypes
    AudioRecapConfigDto:
      type: object
      properties:
        materials:
          description: Material IDs
          type: array
          items:
            type: string
        folders:
          description: Folder IDs
          type: array
          items:
            type: string
        excludedMaterialIds:
          description: >-
            Material IDs to exclude when expanding selected folders. Has no
            effect on materials picked directly via `materials`.
          type: array
          items:
            type: string
        duration:
          type: number
          description: Duration of audio recap in minutes
          example: 10
        numParts:
          type: number
          description: Number of parts to split the audio into
          example: 5
        isMultiVoice:
          type: boolean
          description: Enable multi-voice conversation mode
        voice1:
          type: string
          description: Primary voice for narration
          example: Puck
        voice2:
          type: string
          description: Secondary voice for multi-voice mode
          example: Aoede
        topic:
          type: string
          description: Specific topic to focus on
        theme:
          type: string
          description: Theme or style for the audio recap
        model:
          type: string
          description: AI model to use for generation
          example: gpt-4.1-2025-04-14
        recapType:
          type: string
          enum:
            - SUMMARY
            - LECTURE
            - PODCAST
            - AUDIO_BOOK
          description: Type of audio recap
    ExplainersConfigDto:
      type: object
      properties:
        materials:
          description: Material IDs
          type: array
          items:
            type: string
        folders:
          description: Folder IDs
          type: array
          items:
            type: string
        title:
          type: string
          description: Video title (defaults to component name if not provided)
        model:
          type: string
          description: AI model to use for generation
          example: gpt-4o-mini-2024-07-18
        style:
          type: string
          description: Video style
          example: professional
        targetLength:
          type: number
          description: Target length in seconds
          minimum: 15
          maximum: 1200
        webSearch:
          type: boolean
          description: Enable web search for additional content
        imageSearch:
          type: boolean
          description: Enable image search for visuals
        verticalVideo:
          type: boolean
          description: Create vertical video format (9:16)
    UploadsConfigDto:
      type: object
      properties:
        materials:
          description: Material IDs
          type: array
          items:
            type: string
        folders:
          description: Folder IDs
          type: array
          items:
            type: string
        folderId:
          type: string
          description: Folder ID where uploads will be stored
      required:
        - folderId
    TutorMeConfigDto:
      type: object
      properties:
        materials:
          description: Material IDs
          type: array
          items:
            type: string
        folders:
          description: Folder IDs
          type: array
          items:
            type: string
        tutorPersonality:
          type: string
          description: Tutor personality
        sessionDuration:
          type: number
          description: Session duration in minutes
        enableVideo:
          type: boolean
          description: Enable video
        enableVoice:
          type: boolean
          description: Enable voice
    ChatAnalyticsConfigDto:
      type: object
      properties:
        chatComponentId:
          type: string
          description: ID of the chat component to analyze
        dateRange:
          type: number
          description: Default date range in days
          default: 30
        autoRefresh:
          type: boolean
          description: Enable auto-refresh
        refreshInterval:
          type: number
          description: Refresh interval in minutes
          minimum: 1
          maximum: 60
        showUserStats:
          type: boolean
          description: Show user statistics section
          default: true
        showSummary:
          type: boolean
          description: Show summary section
          default: true
        showTopics:
          type: boolean
          description: Show top topics
          default: true
        enableExport:
          type: boolean
          description: Enable CSV export functionality
          default: true
      required:
        - chatComponentId
    GuardrailRuleDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the rule
        description:
          type: string
          description: Description of the rule
        condition:
          type: string
          description: Condition to check
        action:
          type: string
          enum:
            - block
            - warn
            - modify
          description: Action to take when rule is triggered
        message:
          type: string
          description: Message to show when rule is triggered
      required:
        - id
        - description
        - condition
        - action
    CharacterDto:
      type: object
      properties:
        id:
          type: string
          description: Character ID
        name:
          type: string
          description: Character name
        role:
          type: string
          description: Character role
        description:
          type: string
          description: Character description
      required:
        - id
        - name
        - role
    ToolDto:
      type: object
      properties:
        id:
          type: string
          description: Tool ID
        name:
          type: string
          description: Tool name
        description:
          type: string
          description: Tool description (what it does / shows)
        type:
          type: string
          description: Tool type (e.g. Database, Document)
        dataFormat:
          type: string
          description: Data format provided by the tool
      required:
        - id
        - name
        - description
        - type
    EvaluationCriterionDto:
      type: object
      properties:
        id:
          type: string
          description: Stable identifier for this criterion
        description:
          type: string
          description: What this criterion measures
        weight:
          type: number
          minimum: 1
          maximum: 10
          description: Importance weight 1-10
      required:
        - id
        - description
        - weight
    QuestionDistributionDto:
      type: object
      properties:
        multiplechoice:
          type: number
          description: Number of multiple choice questions
        truefalse:
          type: number
          description: Number of true/false questions
        shortanswer:
          type: number
          description: Number of short answer questions
        frq:
          type: number
          description: Number of free response questions
        fillinblank:
          type: number
          description: Number of fill in the blank questions
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API Key for server-to-server authentication. Resolves to the owning
        organization.

````