The TutorFlow Content API connects an external content system, such as a CMS, a curriculum database, or your own app, to the content educators build in TutorFlow. It serves three jobs:
- Expand your source JSON. Send existing structured content, such as a category, a level, and its lessons, and TutorFlow creates an interactive module, a summary video plan, and an expanded quiz from it. See Source JSON Expansion.
- Control TutorFlow content. Create, read, update, delete, generate, and sync modules, courses, videos, slides, tests, games, and simulations in a classroom, whether your system or an educator created them. See Resources and Generate Tests, Modules, Courses, and Slides.
- Connect the people an educator teaches. Invite and enroll learners, and read their progress and test results, with opt-in learner scopes. See Learners.
What's new: evaluations and a learner model (grade an answer, then read concepts and a learner's mastery), test mode with a sandbox classroom, test, module, course, and slide deck generation, asset uploads, a learner API, ETags for safe concurrent edits, per-key monthly credit limits, a credit history and audit log, and webhook endpoint health. See the Changelog.
How it fits together
| Concept | What it is |
|---|---|
| Base URL | https://api.tutorflow.io. Every route is under /v1/content. |
| Test mode | A test key (tf_content_test_...) works in a private sandbox classroom, with canned generation and renders and no credits ever spent. Start there. See Test Mode. |
| Content API key | A bearer token that starts with tf_content_, scoped to one organization. Create it in TutorFlow under Settings > Content API. See Keys and Authentication. |
| Scopes | content:read, content:write, content:generate (anything that spends AI Credits), and webhooks:manage, plus the opt-in learners:read and learners:write. |
| Classroom | Every resource lives in a classroom. Find ids with GET /v1/content/classrooms. A key can be limited to some classrooms. |
| AI Credits | Reads, writes with content you supply, uploads, and expansions are free. Generation, narration, and video rendering spend the organization's AI Credits, within an optional monthly limit per key. See Pricing. |
| Files | Upload images, clips, audio, and PDFs through presigned URLs and use the returned key in resource fields. See Asset Uploads. |
| Webhooks | Signed events for finished jobs, resource changes, generation runs, builds, renders, and learner activity. See Webhooks. |
| Concurrency | ETag on every single-resource route, with If-Match so an update never overwrites an educator's newer edit. See Concurrency and ETags. |
What the API reaches
| Content type | Collection path under /v1/content/classrooms/{classroomId} | Expansion output | Priced generation |
|---|---|---|---|
| Module: one interactive lesson that educators build and assign | /modules | interactive_module | From a topic |
| Course: chapters and lessons | /courses | None | From a prompt |
| Video: an editable scene plan, rendered to mp4 on request | /videos | summary_video | Rendering |
| Slides: a presentation deck | /slides | None | From a topic |
| Test: an assessment with items and scoring | /tests | expanded_quiz | From a topic |
| Game: a playable web page built from a practice objective | /games | None | Brief, build, revise |
| Simulation: an interactive model learners explore with controls | /simulations | None | Brief, build, revise |
Every route, with its scope and response, is listed once in the API Reference.
Recommended flow
- Create a test key with only the scopes you need, and build against the sandbox classroom. See the Quickstart.
- Call
GET /v1/content/creditsto confirm the key works and to read the balance. - Find the target classroom with
GET /v1/content/classrooms. - Create one resource, or submit one small expansion job, with an
Idempotency-Key. - Poll the job or run until it finishes, then store the returned TutorFlow ids and the result manifest next to your own ids.
- Read and update resources by id if your system must stay in sync.
- Register a webhook once polling works, and move to events for completion and change notifications.
Use the CLI
To try the API from a terminal, or to script it in CI before you write client code, use @tutorflow/cli. It takes the same organization Content API key and makes the same calls:
--wait follows the generation run and prints the finished course with its editorUrl and publicUrl. A key that reaches only one classroom needs no --classroom; you can also set TUTORFLOW_CLASSROOM_ID once. Add --json for machine-readable output. The CLI guide lists every command.
The Agent Platform
The Content API is for content that people create, review, and manage in TutorFlow classrooms. It uses /v1/content/** and tf_content_ keys, and its resources are scoped to classrooms. All TutorFlow content made through an API lives here, including content made by AI agents.
The Agent Platform content routes (/v1/platform/videos, slides, courses, tests, modules, games, evaluations, learners, and Platform webhooks) were removed on 2026-10-16. They answer 410 with error.code platform_route_removed and a migrationGuide link. What remains under /v1/platform/** includes agent account registration, billing, the public pricing catalog, old share-link lookups, and LTI. An agent account is backed by a TutorFlow organization and spends the same credit balance as the Content API and the TutorFlow editor. A tf_platform_ key does not work on /v1/content/**: it gets 401 content_platform_key_not_accepted.
To surface TutorFlow content inside an LMS rather than another content system, see LMS Integration (LTI).
Next steps
- Quickstart: a first successful call in about 5 minutes.
- Test Mode: build without spending credits or touching real classrooms.
- Keys and Authentication
- API Reference
- Examples: every task in curl, Node.js, and Python.
- Credit History and Audit Log: what each key spent and changed.