Migrating to the Content API

The content routes of the Agent Platform are deprecated. Courses, modules, tests, slides, videos, games, evaluations, and the learner model now live on the Content API, under /v1/content/classrooms/{classroomId}/.... The Agent Platform stays as the account layer: registration, the account and its balance, top-ups, pricing, discovery, LTI, and the MCP server.

This guide lists every deprecated route with its replacement and what changes in the answer. The full Content API reference is at Content API Reference.

Timeline

After the sunset, content created on the deprecated routes is planned to be copied into your account's default classroom, and share links already handed out are planned to redirect to the classroom pages. Do not depend on that: move your integration before 2027-01-31.

These stay where they are and are not deprecated:

• /v1/platform/agent/*: register, account, billing, x402, email verification.
• /v1/platform/pricing-catalog and /v1/platform/.well-known/agent.json.
• /v1/platform/health.
• /v1/platform/lti/*, including LTI registrations.
• The MCP server at https://mcp.tutorflow.io/api/mcp.

Deprecation headers

Every answer from a deprecated route, errors included, carries three headers:

Deprecation: @1792022400
Sunset: Sun, 31 Jan 2027 00:00:00 GMT
Link: <https://tutorflow.io/agent-platform/docs/guides/content-api-migration>; rel="deprecation"

Log a warning whenever your client sees Deprecation on an answer. That finds every call you still have to move.

Keys

The Content API takes only tf_content_ keys. Your agent account already has one.

Get a tf_content_ key

• From registration. POST /v1/platform/agent/register returns contentApiKey (a tf_content_ key) next to the legacy apiKey (a tf_platform_ key). Use contentApiKey for everything.
• From the dashboard. Sign in at tutorflow.io, open the Agent Platform dashboard, and create a key. The dashboard creates only tf_content_ keys now. Choose Live or Test as the mode.

The raw key is shown once. Store it in your secrets manager.

Live and test keys

Read both classroom ids from GET /v1/platform/agent/account with a live key. With only a test key, GET /v1/content/classrooms lists the sandbox. See Test Mode.

Which key works where

The two refusals look like this:

{
  "error": {
    "code": "content_platform_key_not_accepted",
    "message": "Agent Platform keys (tf_platform_) do not work on the Content API. Use a tf_content_ key: agent register returns one as contentApiKey, and the agent dashboard issues new ones.",
    "status": 401,
    "requestId": "..."
  }
}

{
  "error": {
    "code": "platform_content_key_not_accepted",
    "message": "This deprecated Platform content route takes tf_platform_ keys only. The same work is on the Content API: call /v1/content with your tf_content_ key. Migration guide: https://tutorflow.io/agent-platform/docs/guides/content-api-migration",
    "status": 401
  }
}

Rotate a key

Rotate or revoke keys in the Agent Platform dashboard. Rotation returns a new raw key once; update your secret store and restart the clients that hold the old one. Rotating a tf_platform_ key gives another tf_platform_ key, which still stops working at the sunset, so create a tf_content_ key instead and revoke the old one once nothing uses it.

The classroom in every URL

Every Content API route sits under a classroom: /v1/content/classrooms/{classroomId}/.... An agent account has one default classroom, created at registration. Read its id once and keep it:

curl https://api.tutorflow.io/v1/platform/agent/account \
  -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY"

{
  "defaultClassroomId": "00000000-0000-4000-8000-000000000010",
  "sandboxClassroomId": null,
  "contentApiBaseUrl": "https://api.tutorflow.io/v1/content",
  "contentApiUrls": {
    "listClassrooms": "GET /v1/content/classrooms",
    "generateCourse": "POST /v1/content/classrooms/00000000-0000-4000-8000-000000000010/courses/generate",
    "listCourses": "GET /v1/content/classrooms/00000000-0000-4000-8000-000000000010/courses",
    "generateSlides": "POST /v1/content/classrooms/00000000-0000-4000-8000-000000000010/slides/generate",
    "generateTest": "POST /v1/content/classrooms/00000000-0000-4000-8000-000000000010/tests/generate",
    "createVideo": "POST /v1/content/classrooms/00000000-0000-4000-8000-000000000010/videos"
  }
}

sandboxClassroomId stays null until the account has a test key.

What changes in the answers

Route map

{classroomId} is your defaultClassroomId. Paths on the right are under /v1/content/classrooms/{classroomId}.

Courses: /v1/platform/courses

See Courses and Course chapters and lessons.

Modules: /v1/platform/modules

Tests: /v1/platform/tests

See Tests and Learners.

Slides: /v1/platform/slides

Videos: /v1/platform/videos

The Content API has no route that writes a whole narrated video from a prompt. You create the video, add and fill its scenes, generate narration from each scene's script, then render. See Videos and Video Rendering.

Games: /v1/platform/games

Evaluations: /v1/platform/evaluations

The request body is the same: evaluationType, questionText, learnerAnswer, referenceAnswer, rubric, maxScore, learnerExternalId or submitter, conceptTags, language, mode, clientMetadata, and the rest. JSON and multipart/form-data with rubricFiles and answerFiles both work.

Learners: /v1/platform/learners

The learner model is kept per organization, so every classroom of the account answers the same.

Webhook endpoints: /v1/platform/webhooks

See Webhooks for testing, rotation, delivery logs, and redelivery.

Webhooks

Your Platform webhook endpoints were copied to Content API endpoints for the same account, with the same URL and the same signing secret. Each copy starts active if the Platform endpoint was active. Events were mapped:

A Platform *.completed event also carried failures, so it maps to both a completed and a failed event. Note that video.render.completed means the mp4 is ready; the Platform's video.completed meant the scenes were written.

What your receiver has to change:

The quickest switch: read X-Content-Integration-Signature where you read X-Platform-Signature, since the value is computed the same way. Then branch on the new event names and payloads. A run event carries runId, resourceId, status, creditsCharged, and error; an evaluation event carries resourceId (the evaluation id), evaluationType, status, learnerExternalId, and the scores or error.

Billing

There is one balance: the classroom credits of the organization behind your account. Content API calls, deprecated Platform calls, and anything a person does in the TutorFlow editor all spend it.

• Your old wallet, kept in cents, was converted once into credits at 2 US cents per credit, rounded down. A wallet that still held only the untouched $1.00 trial grant, with no usage, was not converted. New accounts start with 50 trial credits.
• GET /v1/platform/agent/account answers credits and creditBalance. creditBalance is credits at 2 cents each, in cents, the unit the field always used.
• Top-ups (Stripe checkout and x402 USDC deposits) buy credits at 2 cents per credit.
• With a verified card, the account may overdraw up to its overdraftLimit, and the overdraft is billed by Stripe at 2 cents per credit.
• The deprecated routes now charge the classroom credit amounts, so they cost the same as the Content API.

See Pricing and Billing for the price of each call.

MCP

The MCP server at https://mcp.tutorflow.io/api/mcp accepts both key kinds until the sunset. With a tf_content_ key, create_course, get_course_generation, list_courses, run_evaluation, and list_evaluations call the Content API in your default classroom (the sandbox for a test key). With a tf_platform_ key, create_course, list_courses, run_evaluation, and list_evaluations keep calling the deprecated routes and add a sunset notice to every answer, and get_course_generation is not available. To migrate, change the Authorization header in your MCP client configuration to Bearer tf_content_.... See MCP Integration.

Checklist

1. Get a tf_content_ key from registration or the dashboard, and store it.
2. Read defaultClassroomId from GET /v1/platform/agent/account.
3. Replace each deprecated route with its replacement above. Send topic instead of prompt.
4. Replace synchronous waits with run polling or *.generation.* webhooks.
5. Replace edit and share token handling with editorUrl and publicUrl.
6. Update your webhook receiver to the Content API headers and event names.
7. Switch the MCP client configuration to the tf_content_ key.
8. Watch your logs for answers with a Deprecation header until none are left.