API Reference

Base URL

https://api.tutorflow.io/v1/platform

Authentication

External endpoints require a valid Platform API key passed via the Authorization header. Internal management endpoints are authenticated through TutorFlow admin auth and are intentionally not enumerated in public agent documentation. See Authentication for details.

Endpoints Overview

Evaluations (API Key required)

Method	Endpoint	Description
`POST`	`/evaluations`	Create an evaluation request
`GET`	`/evaluations/:id`	Get evaluation result
`GET`	`/evaluations/:id/files/:field/:index`	Download evaluation files
`GET`	`/evaluations`	List evaluation requests. Supports `learnerId` filter

Learners (API Key required)

Method	Endpoint	Description
`GET`	`/learners`	List learners with aggregate evaluation stats
`GET`	`/learners/:learnerId`	Get learner profile with per-concept mastery summaries

Courses (API Key and token-gated routes)

Method	Endpoint	Description
`POST`	`/courses`	Create a course generation request
`GET`	`/courses/:id`	Get course by ID
`GET`	`/courses`	List course requests
`PATCH`	`/courses/:id`	Update course metadata
`PATCH`	`/courses/:id/canonical`	Bulk-update course metadata, chapters, and lessons
`PATCH`	`/courses/:id/chapters/:chapterId`	Update one chapter
`PATCH`	`/courses/:id/lessons/:sequence`	Update one lesson by sequence
`PATCH`	`/courses/:id/lessons/by-id/:lessonId/full`	Update one full lesson by UUID
`POST`	`/courses/:id/edit-token`	Generate an edit token for a course
`GET`	`/courses/public/:shareToken`	Get public course by share token
`GET`	`/courses/public/:shareToken/full`	Get full public course with lessons
`GET`	`/courses/public/:shareToken/lessons/:sequence`	Get public lesson by sequence
`GET`	`/courses/edit/:editToken`	Get course by edit token
`GET`	`/courses/edit/:editToken/full`	Get full course with lessons
`GET`	`/courses/edit/:editToken/lessons/:sequence`	Get lesson by edit token
`PATCH`	`/courses/edit/:editToken/lessons/:sequence`	Update lesson by edit token
`GET`	`/courses/edit/:editToken/canonical`	Get canonical course payload by edit token
`PATCH`	`/courses/edit/:editToken/canonical`	Bulk-update canonical course payload by edit token
`GET`	`/courses/edit/:editToken/lessons/by-id/:lessonId/full`	Get one full lesson by UUID and edit token
`POST`	`/courses/edit/:editToken/lessons/by-id/:lessonId/generate`	Generate one lesson's lecture, quizzes, or practice content
`PATCH`	`/courses/edit/:editToken/lessons/by-id/:lessonId/full`	Update one full lesson by UUID and edit token
`PATCH`	`/courses/edit/:editToken`	Update course by edit token
`POST`	`/courses/edit/:editToken/lessons`	Add a new lesson to a course
`POST`	`/courses/edit/:editToken/infer-type`	Infer best lesson type from title/context

Method	Endpoint	Description
`POST`	`/modules`	Create one generated module/standalone lesson
`GET`	`/modules/:id`	Get module by ID
`GET`	`/modules`	List modules
`PATCH`	`/modules/:id`	Update module fields and quizzes
`DELETE`	`/modules/:id`	Soft-delete a module
`GET`	`/modules/public/:shareToken`	Public read-only module viewer payload

Tests (API Key and token-gated routes)

Method	Endpoint	Description
`POST`	`/tests`	Create a test generation request
`GET`	`/tests/:id`	Get test by ID
`GET`	`/tests`	List test requests
`PATCH`	`/tests/:id`	Update test metadata
`PATCH`	`/tests/:id/full`	Bulk-update test metadata and items
`PATCH`	`/tests/:id/items/by-id/:itemId`	Update one test item by UUID
`POST`	`/tests/:id/edit-token`	Generate an edit token for a test
`GET`	`/tests/:id/submissions`	List submissions for a test
`GET`	`/tests/public/:shareToken`	Get public test by share token
`GET`	`/tests/public/:shareToken/full`	Get full public test with items and answers
`GET`	`/tests/public/:shareToken/items/:sequence`	Get public item by sequence
`GET`	`/tests/public/:shareToken/take`	Get test for taking (no answers)
`POST`	`/tests/public/:shareToken/submissions`	Start a test submission
`PATCH`	`/tests/submissions/:submissionToken`	Save or finalize submission answers
`GET`	`/tests/submissions/:submissionToken/result`	Get the latest submission state (in-progress or finalized)
`GET`	`/tests/edit/:editToken`	Get test by edit token (no API key)
`GET`	`/tests/edit/:editToken/full`	Get full test with items by edit token (no API key)
`GET`	`/tests/edit/:editToken/items/:sequence`	Get item by edit token (no API key)
`PATCH`	`/tests/edit/:editToken`	Update test title or description (no API key)
`PATCH`	`/tests/edit/:editToken/full`	Bulk update for title, description, level, timeLimit, and items (no API key)
`POST`	`/tests/edit/:editToken/items`	Create a single item (no API key)
`PATCH`	`/tests/edit/:editToken/items/by-id/:itemId`	Update item by UUID (no API key)
`DELETE`	`/tests/edit/:editToken/items/by-id/:itemId`	Delete item by UUID (no API key)
`PATCH`	`/tests/edit/:editToken/items/reorder`	Reorder items (no API key)
`POST`	`/tests/edit/:editToken/items/generate`	Generate additional items via AI, sync (no API key)
`PATCH`	`/tests/edit/:editToken/items/:sequence`	Update item by sequence, legacy (no API key)

Slides (API Key and token-gated routes)

Method	Endpoint	Description
`POST`	`/slides`	Create a slide-deck generation request
`GET`	`/slides/:id`	Get slide request by ID
`GET`	`/slides`	List slide requests
`PATCH`	`/slides/:id`	Update slide metadata and content
`GET`	`/slides/edit/:editToken`	Get slide content + outline by edit token (no API key)
`PATCH`	`/slides/edit/:editToken`	Update title, description, outline, content, etc.
`POST`	`/slides/edit/:editToken/generate/image`	Generate a single AI image (no API key)
`POST`	`/slides/edit/:editToken/pptx`	Export to PowerPoint (no API key)
`GET`	`/slides/public/:shareToken`	Public read-only viewer (no API key)

Videos (API Key and token-gated routes)

Method	Endpoint	Description
`POST`	`/videos`	Create a narrated-video generation request
`GET`	`/videos/:id`	Get video request by ID (includes renderStatus)
`GET`	`/videos`	List video requests
`PATCH`	`/videos/:id`	Update video metadata
`POST`	`/videos/:id/scenes`	Add a scene
`PATCH`	`/videos/:id/scenes/:sceneId`	Update a scene
`DELETE`	`/videos/:id/scenes/:sceneId`	Delete a scene
`PUT`	`/videos/:id/scenes/reorder`	Reorder scenes
`GET`	`/videos/edit/:editToken`	Get full video + scenes by edit token (no API key)
`PATCH`	`/videos/edit/:editToken`	Update video metadata (title, BGM, aspect, etc.)
`POST`	`/videos/edit/:editToken/scenes`	Add a scene
`PATCH`	`/videos/edit/:editToken/scenes/:sceneId`	Update a scene
`DELETE`	`/videos/edit/:editToken/scenes/:sceneId`	Delete a scene
`PUT`	`/videos/edit/:editToken/scenes/reorder`	Reorder scenes
`POST`	`/videos/edit/:editToken/scenes/:sceneId/tts`	Regenerate TTS for a scene
`POST`	`/videos/edit/:editToken/scenes/:sceneId/clip/search`	Search Pexels + Pixabay for stock clips
`POST`	`/videos/edit/:editToken/scenes/:sceneId/clip/select`	Apply a selected stock clip
`POST`	`/videos/edit/:editToken/scenes/:sceneId/clip/upload`	Upload a custom clip (multipart)
`POST`	`/videos/edit/:editToken/scenes/:sceneId/visual/image/upload`	Upload a custom image visual (multipart)
`POST`	`/videos/edit/:editToken/scenes/:sceneId/overlays/sticker/upload`	Upload a sticker overlay image (multipart)
`POST`	`/videos/edit/:editToken/scenes/:sceneId/overlays/character/generate`	Generate a character sticker overlay
`GET`	`/videos/edit/:editToken/visual/slides`	List available slide visuals for this video
`POST`	`/videos/edit/:editToken/scenes/:sceneId/visual/slide`	Use an existing slide as a scene visual
`POST`	`/videos/edit/:editToken/scenes/:sceneId/visual/slide/create`	Create a new slide visual for a scene
`POST`	`/videos/edit/:editToken/sync-durations`	Recompute scene durations from TTS audio
`POST`	`/videos/edit/:editToken/thumbnail`	Upload a thumbnail image (multipart)
`POST`	`/videos/edit/:editToken/bgm/search`	Search BGM presets
`POST`	`/videos/edit/:editToken/bgm/select`	Apply a BGM preset
`DELETE`	`/videos/edit/:editToken/bgm`	Remove BGM
`POST`	`/videos/edit/:editToken/render`	Start a Remotion render
`POST`	`/videos/edit/:editToken/render/cancel`	Cancel an in-progress render
`GET`	`/videos/public/:shareToken`	Public read-only viewer (no API key)

Agent Self-Service

See Agent Self-Service API for request bodies, response fields, and recovery errors.

Method	Endpoint	Auth	Description
`GET`	`/pricing-catalog`	None	Live per-unit pricing catalog
`GET`	`/.well-known/agent.json`	None	Service discovery manifest
`POST`	`/agent/register`	None (IP throttled)	Self-service registration
`GET`	`/agent/verify-email`	None	Verify workspace email. Requires `token` query parameter
`POST`	`/agent/verify-email/resend`	API Key	Resend verification email
`POST`	`/agent/billing/session`	API Key	Get checkout page URL for credit purchase. Requires verified email
`GET`	`/agent/billing/status`	API Key	Billing status and payment method info
`GET`	`/agent/account`	API Key	Workspace info and credit balance
`GET`	`/agent/checkout`	None	Validate a billing checkout token. Requires `token` query parameter
`POST`	`/agent/checkout`	None	Create Stripe session from checkout token

LTI 1.3 Integration

Method	Endpoint	Auth	Description
`POST`	`/lti/registrations`	API Key	Create an LTI registration
`GET`	`/lti/registrations`	API Key	List LTI registrations
`GET`	`/lti/registrations/:id`	API Key	Get an LTI registration
`PUT`	`/lti/registrations/:id`	API Key	Update an LTI registration
`DELETE`	`/lti/registrations/:id`	API Key	Deactivate an LTI registration
`GET`	`/lti/login`	None	OIDC login initiation (called by LMS)
`POST`	`/lti/launch`	None	Launch callback (called by LMS)
`POST`	`/lti/deep-linking/response`	None	Deep linking response callback
`GET`	`/lti/.well-known/jwks.json`	None	Public JWKS endpoint

Health

Method	Endpoint	Auth	Description
`GET`	`/health`	API Key	Health check (validates API key)

MCP

Agents can also connect via the Model Context Protocol instead of calling REST endpoints directly.

Transport	URL
Streamable HTTP	`https://mcp.tutorflow.io/api/mcp`

Internal and Dashboard APIs

TutorFlow also has dashboard and internal management APIs for workspace administration, key management, webhook setup, usage inspection, and billing operations. They are intentionally not enumerated in the public agent docs because they are not callable with Platform API keys and are meant for TutorFlow dashboard or admin-auth surfaces.

Agents should use:

POST /v1/platform/agent/register for first key creation
GET /v1/platform/agent/account and GET /v1/platform/agent/billing/status for self-service state
POST /v1/platform/agent/billing/session for human-approved credit top-up

Response Format

All responses return JSON. Successful responses include the resource directly:

{
  "id": "uuid",
  "status": "COMPLETED",
  "evaluationType": "open_ended",
  "score": 8,
  "feedbackSummary": "Strong answer..."
}

External Platform API key error responses follow this format:

{
  "error": {
    "code": "platform_invalid_request",
    "message": "Validation failed",
    "status": 422
  }
}

Validation failures usually return HTTP 422 with error.code: "platform_invalid_request". Some malformed requests can return HTTP 400 with the same code. Agents should branch on error.code first.