Skip to main content

​
Overview

The Scenarios component creates interactive learning experiences through case studies, role-playing exercises, and problem-solving scenarios. These immersive experiences help students apply theoretical knowledge in practical contexts. You can create scenarios components through the API. Optionally pass criteria to define how student performance is graded; if you omit it or send an empty list, the AI generates criteria at create time.
Validation on create and update. When you provide characters, tools, or criteria, every entry must include its required fields:
  • Character — id, name, role
  • Tool — id, name, description, type
  • Evaluation criterion — id, description, weight (number, 1–10)
Send an empty array (or omit the field) to let the AI fill it in at create time. Updates are not auto-filled, so any item you send must already be complete.Narrative fields on update. On a PUT/PATCH to a scenarios component, the server merges your changes with the existing scenario and then requires the merged result to keep these non-empty:
  • context, goal, greetingMessage
  • finalAnswerPrompt — only when requiresFinalAnswer is true
format is optional — leave it empty and the runtime falls back to a generic conversational interaction.Partial updates (sending just criteria, just tools, etc.) are fine — the existing values fill in. The call only fails (400 Bad Request) if your update would clear one of the required fields above.

​
Creating a Scenarios Component

import StudyfetchSDK from '@studyfetch/sdk';

const client = new StudyfetchSDK({
  apiKey: 'your-api-key',
  baseURL: 'https://studyfetchapi.com',
});

const scenarioComponent = await client.v1.components.create({
  name: 'Medical Emergency Room Scenario',
  type: 'scenarios',
  config: {
    context: 'You are a medical resident in a busy emergency room. A patient has just arrived with chest pain.',
    goal: 'Properly assess the patient, order appropriate tests, and make a diagnosis',
    format: 'Interactive dialogue with patient and medical staff',
    greetingMessage: 'Welcome Dr. [Student Name]. Your patient, Mr. Johnson, has just arrived in room 3 complaining of chest pain.',
    greetingCharacterId: 'nurse-jane',
    requiresFinalAnswer: true,
    finalAnswerPrompt: 'Based on your assessment, what is your diagnosis and treatment plan?',
    criteria: [
      { id: 'history-taking', description: 'Structured history and focused questions', weight: 7 },
      { id: 'clinical-reasoning', description: 'Sound differential and next steps', weight: 8 },
    ],
    characters: [
      {
        id: 'patient-johnson',
        name: 'Mr. Johnson',
        role: 'Patient',
        description: '58-year-old male with chest pain'
      },
      {
        id: 'nurse-jane',
        name: 'Nurse Jane',
        role: 'Emergency Room Nurse',
        description: 'Experienced ER nurse who assists with procedures'
      }
    ],
    tools: [
      {
        id: 'ekg-machine',
        name: 'EKG Machine',
        description: 'Performs 12-lead electrocardiogram',
        type: 'diagnostic',
        dataFormat: 'EKG readings with intervals and interpretation'
      },
      {
        id: 'lab-results',
        name: 'Lab Results System',
        description: 'Provides blood test results',
        type: 'diagnostic',
        dataFormat: 'Complete blood count, cardiac enzymes, etc.'
      }
    ]
  }
});

console.log('Scenario component created:', scenarioComponent._id);

​
Configuration Parameters

​
name
string
required
Name of the scenarios component
​
type
string
required
Must be "scenarios"
​
config
object
required
Scenarios configuration object

​
Response

{
  "_id": "comp_101jkl",
  "name": "Medical Emergency Room Scenario",
  "type": "scenarios",
  "status": "active",
  "config": {
    "context": "You are a medical resident in a busy emergency room. A patient has just arrived with chest pain.",
    "goal": "Properly assess the patient, order appropriate tests, and make a diagnosis",
    "format": "Interactive dialogue with patient and medical staff",
    "greetingMessage": "Welcome Dr. [Student Name]. Your patient, Mr. Johnson, has just arrived in room 3 complaining of chest pain.",
    "greetingCharacterId": "nurse-jane",
    "requiresFinalAnswer": true,
    "finalAnswerPrompt": "Based on your assessment, what is your diagnosis and treatment plan?",
    "criteria": [
      { "id": "history-taking", "description": "Structured history and focused questions", "weight": 7 },
      { "id": "clinical-reasoning", "description": "Sound differential and next steps", "weight": 8 }
    ],
    "characters": [
      {
        "id": "patient-johnson",
        "name": "Mr. Johnson",
        "role": "Patient",
        "description": "58-year-old male with chest pain"
      },
      {
        "id": "nurse-jane",
        "name": "Nurse Jane",
        "role": "Emergency Room Nurse",
        "description": "Experienced ER nurse who assists with procedures"
      }
    ],
    "tools": [
      {
        "id": "ekg-machine",
        "name": "EKG Machine",
        "description": "Performs 12-lead electrocardiogram",
        "type": "diagnostic",
        "dataFormat": "EKG readings with intervals and interpretation"
      },
      {
        "id": "lab-results",
        "name": "Lab Results System",
        "description": "Provides blood test results",
        "type": "diagnostic",
        "dataFormat": "Complete blood count, cardiac enzymes, etc."
      }
    ]
  },
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:00:00Z",
  "organizationId": "org_456def"
}

​
Embedding This Component

Once you’ve created a Scenarios component, you can embed it on your website using the embedding API.

​
Generate Embed URL

const embedResponse = await client.v1.components.generateEmbed(scenarioComponent._id, {
  // User tracking
  userId: 'user-456',
  studentName: 'Jane Smith',  // Student name for display
  groupIds: ['class-101', 'class-102'],
  sessionId: 'session-789',
  
  // Scenarios-specific features
  features: {
    enableHistory: true
  },
  
  // Dimensions
  width: '100%',
  height: '600px',
  
  // Token expiry
  expiryHours: 24
});

​
Scenarios-Specific Embedding Features

​
features.enableHistory
boolean
default:"true"
Save scenario progress and allow users to resume where they left off

​
Embed in Your HTML

<iframe 
  src="https://embed.studyfetch.com/component/comp_101jkl?token=..."
  width="100%"
  height="600px"
  frameborder="0"
  style="border: 1px solid #e5e5e5; border-radius: 8px;">
</iframe>