Content Integration accepts existing source JSON as the input of record. Use this guide when another content system already owns the content structure and needs TutorFlow to create reusable authoring outputs from it.

Minimum shape

{
  "category": {
    "id": "language-basics",
    "title": "Language Basics"
  },
  "language": "en",
  "level": {
    "id": "level-a1",
    "title": "A1 Foundations",
    "lessons": [
      {
        "id": "lesson-1",
        "type": "vocabulary",
        "title": "Basic greetings",
        "items": [
          {
            "term": "hello",
            "meaning": "a greeting",
            "example": "Hello, Mina."
          }
        ]
      }
    ]
  }
}

Full example

Use one category and one level for the first integration test. Include the source system's real field names. TutorFlow keeps unknown fields in the prompt context, so the external system does not need to pre-convert content before submission.

{
  "category": {
    "id": "language-basics",
    "title": "Language Basics"
  },
  "language": "en",
  "level": {
    "id": "level-a1",
    "title": "A1 Foundations",
    "lessons": [
      {
        "id": "lesson-vocabulary-1",
        "type": "vocabulary",
        "title": "Basic greetings",
        "items": [
          {
            "term": "hello",
            "meaning": "a greeting used when meeting someone",
            "example": "Hello, Mina."
          }
        ]
      },
      {
        "id": "lesson-example-1",
        "type": "example",
        "title": "Greeting examples",
        "examples": [
          {
            "source": "Good morning.",
            "translation": "A greeting used in the morning.",
            "note": "Use this before noon."
          }
        ]
      },
      {
        "id": "lesson-dialogue-1",
        "type": "dialogue",
        "title": "Meeting a classmate",
        "turns": [
          {
            "speaker": "A",
            "text": "Hello. What is your name?"
          },
          {
            "speaker": "B",
            "text": "My name is Mina."
          }
        ]
      },
      {
        "id": "lesson-check-1",
        "type": "quiz",
        "title": "Greeting check",
        "questions": [
          {
            "question": "Which phrase is a greeting?",
            "choices": ["Hello", "Blue", "Desk"],
            "answer": "Hello",
            "explanation": "Hello is used to greet someone."
          }
        ]
      },
      {
        "id": "lesson-review-1",
        "type": "review",
        "title": "Level review",
        "summary": "Review greetings, names, and simple introductions.",
        "keyPoints": ["hello", "my name is", "good morning"]
      }
    ]
  }
}

Lesson type handling

The integration keeps lesson order and preserves unknown fields in the prompt context. Use the source system's existing lesson type names. The examples below are common patterns, not required enum values.

Pattern	Expected content	Returned expansion behavior
`vocabulary`	Terms, meanings, examples, glossary entries	Becomes guided concept explanation, practice checks, and review prompts.
`example`	Usage examples, translations, notes, explanations	Becomes worked examples and instructor-style explanation blocks.
`dialogue`	Speaker turns and conversational practice	Becomes role-play prompts, comprehension checks, and video scene material.
`quiz`	Existing checks, answer keys, hints, explanations	Seeds expanded quiz items while preserving answer intent.
`review`	Summary, key points, level review content	Becomes wrap-up sections, recap scenes, and final review questions.

If the source system uses different type names, keep the original values. TutorFlow maps them during integration setup.

Payload guidance

Include stable ids for category, level, and lessons.
Keep source text, examples, answer keys, hints, and explanations in the payload.
Include language or locale if the content is not English.
Do not pre-convert lesson text into TutorFlow formats. Send the current JSON structure.
Send one level or similarly small content group for the first test so output review stays manageable.

Field mapping

TutorFlow reads a small set of common fields and keeps the rest as source context.

Source field	Recommended shape	How TutorFlow uses it
`category.id`	Stable string	Traceability back to the source category.
`category.title`	Human-readable title	Used in `sourceTitle` and output descriptions.
`language` or `locale`	BCP 47 style string, such as `en` or `ko`	Guides output language and copy tone.
`level.id`	Stable string	Traceability back to the source level.
`level.title`	Human-readable title	Used in module, video, and quiz titles.
`level.lessons[]`	Ordered array	Preserved as the teaching sequence.
`lesson.id`	Stable string	Used for lesson-level traceability.
`lesson.type`	Source system's current type	Used to infer the best expansion pattern.
`lesson.title`	Human-readable title	Used in section and scene planning.
Unknown fields	Any valid JSON value	Preserved in source context for generation.

Idempotency key design

Use an idempotency key that identifies the exact source content group and version.

Good examples:

language-basics:level-a1:2026-07-04
category-language-basics-level-a1-schema-v3
source-system-12345-level-a1-content-hash-8f21c

Avoid keys that change on every retry, such as timestamps generated at request time. A stable key prevents duplicate TutorFlow jobs when the external system retries after a network timeout.

Validation checklist

The payload is valid JSON.
The level or content group contains at least one lesson.
Each lesson has a stable id and type.
Quiz answers are included when available.
The customer can process and submit the source content.

Common payload mistakes

Mistake	Result	Fix
`level.lessons` is empty	The request is rejected.	Include at least one lesson in the first test payload.
Lesson content is flattened into one long string	Output quality is harder to review.	Keep terms, examples, dialogue turns, and quiz items as structured fields.
Quiz answers are omitted	Expanded quiz output may not preserve original answer intent.	Include answer keys, explanations, and hints when available.
Source ids are unstable	Reconciliation becomes difficult.	Use ids that remain stable across retries and exports.
Payload is pre-converted to TutorFlow internals	Integration becomes brittle.	Send the source system's current JSON structure.

Source JSON Payload