Components
Create a new component
OpenAPI specificationPOST
/api/v1/componentsAuthentication
x-api-key
Request
curl --globoff --request POST \
--url 'https://api.example.com/api/v1/components' \
--header 'x-api-key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
"type": "chat",
"name": "My Study Component",
"config": {
"model": "gpt-4o-mini-2024-07-18"
}
}'Replace credential and <field> placeholders with your own values. URL placeholders appear as %3Cfield%3E. Review the example values before sending your request.
Replace https://api.example.com with the API server URL.
Use the sample JSON body as your starting point, and enter values that match the endpoint's schema.
Request body schema or example
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"chat",
"data_analyst",
"flashcards",
"scenarios",
"practice_test",
"audio_recap",
"tutor_me",
"explainers",
"uploads",
"chat_analytics",
"video_generation",
"performance_insights"
],
"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": [
{
"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": {
"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"
]
}
},
"enableReferenceMode": {
"type": "boolean",
"description": "Enable reference mode - show references instead of source content"
},
"enableFeedback": {
"type": "boolean",
"description": "Enable thumbs up/down feedback with reason",
"default": true
},
"hideTitle": {
"type": "boolean",
"description": "Hide the chat title and avatar in the embedded component"
},
"emptyStateHtml": {
"type": "string",
"description": "Custom HTML to show in empty state instead of default icon and text"
},
"hideEmptyState": {
"type": "boolean",
"description": "Hide the default empty state (icon and text)"
}
},
"required": [
"model"
]
},
{
"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"
]
},
{
"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"
}
}
},
{
"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": {
"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"
]
}
},
"tools": {
"description": "Available tools",
"type": "array",
"items": {
"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"
]
}
},
"criteria": {
"description": "Authored evaluation criteria. If omitted/empty at create time, the AI will generate criteria.",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this criterion"
},
"description": {
"type": "string",
"description": "What this criterion measures"
},
"weight": {
"type": "number",
"description": "Importance weight 1-10",
"minimum": 1,
"maximum": 10
}
},
"required": [
"id",
"description",
"weight"
]
}
},
"enableHistory": {
"type": "boolean",
"description": "Enable history"
},
"enableVoice": {
"type": "boolean",
"description": "Enable voice"
},
"placeholderText": {
"type": "string",
"description": "Placeholder text"
}
}
},
{
"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": [
{
"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"
}
}
}
]
}
},
"required": [
"questionTypes"
]
},
{
"type": "object",
"properties": {
"materials": {
"description": "Material IDs",
"type": "array",
"items": {
"type": "string"
}
},
"folders": {
"description": "Folder IDs",
"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": "Secondary voice for multi-voice mode. Public names: Alex, Morgan, Riley, Jordan, Sparky, Taylor.",
"enum": [
"Alex",
"Morgan",
"Riley",
"Jordan",
"Sparky",
"Taylor"
]
},
"voice2": {
"type": "string",
"description": "Secondary voice for multi-voice mode. Public names: Alex, Morgan, Riley, Jordan, Sparky, Taylor.",
"enum": [
"Alex",
"Morgan",
"Riley",
"Jordan",
"Sparky",
"Taylor"
]
},
"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"
},
"excludedMaterialIds": {
"description": "Material IDs to exclude when expanding selected folders. Has no effect on materials picked directly via `materials`.",
"type": "array",
"items": {
"type": "string"
}
}
}
},
{
"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)"
}
}
},
{
"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"
]
},
{
"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"
}
}
},
{
"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"
]
}
]
},
"metadata": {
"type": "object",
"description": "Additional metadata"
}
},
"required": [
"type",
"name",
"config"
]
}Responses
201Component created successfully
{
"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",
"video_generation",
"performance_insights"
]
},
"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"
]
}