Source JSON Expansion

An expansion job takes one level of your existing lesson JSON and creates editable TutorFlow content from it in a classroom: an interactive module, a summary video plan, and an expanded quiz. Your JSON stays the input of record; the job result tells you which TutorFlow resources came from it.

• The shape of the JSON, and what TutorFlow reads from it, is in Source JSON Format.
• Keys and scopes are in Keys and Authentication. Creating a job needs content:generate; reading it needs content:read.
• Prices are in Pricing.

The flow

1. POST /v1/content/integrations/expansions with a classroom id, the outputs you want, and your JSON. Store the returned job id.
2. Poll GET /v1/content/integrations/expansions/{jobId} until status is completed or failed, or subscribe to the content.completed and content.failed webhooks.
3. Read GET /v1/content/integrations/expansions/{jobId}/result and store each output's resourceType, resourceId, and manifest next to your source ids.
4. Review the created module, video, and test in TutorFlow, or read and edit them with the resource routes.

Outputs

Outputs always run in this order. Omit requestedOutputs to get all three.

Create a job

POST /v1/content/integrations/expansions
Authorization: Bearer tf_content_...
Content-Type: application/json
Idempotency-Key: expansion:language-basics-a1:v1

{
  "classroomId": "00000000-0000-4000-8000-000000000010",
  "requestedOutputs": ["interactive_module", "summary_video", "expanded_quiz"],
  "payload": {
    "language": "en",
    "category": { "id": "language-basics", "title": "Language Basics" },
    "level": {
      "id": "level-a1",
      "title": "A1 Foundations",
      "lessons": [
        {
          "id": "lesson-greetings",
          "type": "vocabulary",
          "title": "Basic greetings",
          "items": [{ "term": "hello", "meaning": "a greeting", "example": "Hello, Mina." }]
        }
      ]
    }
  }
}

Before the job is queued, TutorFlow checks that payload contains a level with at least one lesson (400 if not). Expansion jobs are free: they create editable drafts without calling a model, so no credit balance is needed.

Response 202:

{
  "id": "00000000-0000-4000-8000-000000000030",
  "sourceType": "source_json",
  "status": "queued",
  "sourceTitle": "Language Basics, A1 Foundations",
  "requestedOutputs": ["interactive_module", "summary_video", "expanded_quiz"],
  "classroomId": "00000000-0000-4000-8000-000000000010",
  "sourceResourceId": null,
  "sourceResourceType": null,
  "error": null,
  "completedAt": null,
  "createdAt": "2026-09-30T09:00:00.000Z",
  "updatedAt": "2026-09-30T09:00:00.000Z",
  "outputs": [
    {
      "id": "00000000-0000-4000-8000-000000000031",
      "outputType": "interactive_module",
      "status": "queued",
      "resourceType": null,
      "resourceId": null,
      "manifest": null,
      "error": null,
      "completedAt": null,
      "creditAmount": 0,
      "creditChargedAt": null
    }
  ]
}

The response lists one output row per requested output; the example shows one.

Idempotency for expansion jobs

Expansion jobs follow the same idempotency rules as every other create. Send the key in the Idempotency-Key header or as idempotencyKey in the body; moving it from one to the other is still the same request.

So:

• Use one key per source content version, for example expansion:{sourceLevelId}:v{sourceVersion}.
• When the source changes, change the key. The same key with the changed source returns 409.
• Never generate the key from the current time; a retry after a timeout must send the same key.

Jobs created before 2026-09-30 with an idempotencyKey are still returned for that key, organization-wide and with no expiry, now with Idempotent-Replayed: true. Such a key that belongs to a job in a classroom your key is not allowed to use returns 409.

Poll the job

GET /v1/content/integrations/expansions/{jobId}
Authorization: Bearer tf_content_...

The response has the same shape as the create response.

A job is tried up to 3 times, 5 and then 25 seconds apart. The content.failed webhook is sent once, after the final attempt; attempts that are tried again send nothing. A job whose server stops is picked up again by another server after about two minutes, and an attempt cut short by a normal server restart is not counted. In a rare case, a job interrupted by a restart right after it finished can send content.completed twice, so skip job ids you have already handled.

A copy-paste poll loop that honors 429 is in the Quickstart, and in Node.js and Python in Examples.

Read the result

GET /v1/content/integrations/expansions/{jobId}/result
Authorization: Bearer tf_content_...

The result has three parts: job (the job fields), outputs (one row per output), and manifest (the job id, status, and every output's manifest in one object).

{
  "job": {
    "id": "00000000-0000-4000-8000-000000000030",
    "sourceType": "source_json",
    "status": "completed",
    "sourceTitle": "Language Basics, A1 Foundations",
    "requestedOutputs": ["interactive_module", "summary_video", "expanded_quiz"],
    "classroomId": "00000000-0000-4000-8000-000000000010",
    "error": null,
    "completedAt": "2026-09-30T09:00:08.000Z",
    "createdAt": "2026-09-30T09:00:00.000Z",
    "updatedAt": "2026-09-30T09:00:08.000Z"
  },
  "outputs": [
    {
      "id": "00000000-0000-4000-8000-000000000031",
      "outputType": "interactive_module",
      "status": "completed",
      "resourceType": "module",
      "resourceId": "00000000-0000-4000-8000-000000000101",
      "manifest": {
        "outputType": "interactive_module",
        "resourceType": "module",
        "resourceId": "00000000-0000-4000-8000-000000000101",
        "title": "A1 Foundations module",
        "description": "Interactive module generated from Language Basics, A1 Foundations.",
        "status": "ready",
        "urls": { "publicUrl": null, "previewUrl": null },
        "externalRefs": { "videoId": null, "classroomTestId": null },
        "completedAt": null,
        "raw": {
          "id": "00000000-0000-4000-8000-000000000101",
          "title": "A1 Foundations module",
          "description": "Interactive module generated from Language Basics, A1 Foundations.",
          "type": "text",
          "status": "ready",
          "slug": "a1-foundations-module",
          "isPublic": false,
          "classroomId": "00000000-0000-4000-8000-000000000010",
          "createdAt": "2026-09-30T09:00:02.000Z",
          "updatedAt": "2026-09-30T09:00:02.000Z"
        }
      },
      "error": null,
      "completedAt": "2026-09-30T09:00:03.000Z",
      "creditAmount": 0,
      "creditChargedAt": null
    }
  ],
  "manifest": {
    "id": "00000000-0000-4000-8000-000000000030",
    "status": "completed",
    "sourceType": "source_json",
    "sourceTitle": "Language Basics, A1 Foundations",
    "outputs": [{ "outputType": "interactive_module", "resourceType": "module", "resourceId": "00000000-0000-4000-8000-000000000101" }]
  }
}

The example shows one output, and job and manifest.outputs are shortened. Store these fields:

Errors

All errors use the envelope in Errors, for example:

{
  "error": {
    "code": "content_invalid_api_key",
    "message": "Invalid or missing Content Integration API key",
    "status": 401,
    "requestId": "3f0c2a9e-6b1d-4c8e-9f2a-7d5b1e0c4a11"
  }
}