Versioning and Deprecation

The Content API is versioned in the path. Every route in these docs is under /v1/content. This page describes what /v1 promises and how changes reach you.

What /v1 guarantees

Within /v1, TutorFlow does not:

• Remove a route, a documented request field, or a documented response field without the deprecation process below.
• Rename a field, or change its type or its meaning.
• Make an optional request field required, or add a new required request field.
• Change the status code or the error.code of a documented outcome.
• Change what a price in Pricing buys without announcing it in the Changelog first.

Additive changes

These can ship in /v1 at any time, and are listed in the Changelog:

• New routes, new optional request fields, and new query parameters.
• New fields in a response object.
• New error.code values for outcomes that were not documented before.
• New webhook event types. You receive only the events an endpoint subscribes to, so a new type never arrives unasked.
• New values in a field documented as open, such as phase or stage in a generation event.

Write clients that tolerate them: ignore response fields you do not know, branch on error.code with a default branch, and do not fail on an unknown enum value in a field you only display.

Breaking changes

A change that breaks the guarantees above goes to a new path version, /v2, or follows the deprecation process for one field or route. When a /v2 exists, /v1 keeps working for at least 12 months after the /v2 announcement.

Security fixes are the exception. If a response exposed data it should not have, the field is removed at once and the removal is listed in the Changelog. The 2026-09-30 removal of internal storage keys and learner contact details was such a fix. So is the 2026-10-01 check that refuses storage keys from outside the calling classroom (400) and test item ids that belong to another test (404).

Deprecation process

1. The field or route is marked deprecated in these docs, in the Changelog, and in the OpenAPI description, with its replacement. Responses that carry it announce it in headers.
2. It keeps working unchanged for at least 6 months, until its sunset date.
3. The sunset date is set when the deprecation is announced and does not change.
4. On the sunset date it stops being sent, or the route answers 410.

Current deprecations

The sunset date of 2027-04-30 is final: from that day these keys are no longer sent and take is no longer read, so move to the replacements before then. Module, slide, and test updates now answer with the updated resource plus success: true, so a client that reads success keeps working until the sunset while it moves to the resource fields.

Deprecation headers

A response that still carries a deprecated alias says so in three headers:

Deprecation: @1790726400
Sunset: Fri, 30 Apr 2027 00:00:00 GMT
Link: <https://tutorflow.io/resources/integrations/content-api-versioning>; rel="deprecation"

• Deprecation (RFC 9745) is the Unix time of 2026-09-30T00:00:00Z, when the aliases were deprecated.
• Sunset (RFC 8594) is the date they stop being sent.
• Link points to this page.

They are sent on module, course, slide, test, game, and simulation lists (items, totalCount), on the video list (total), on resource deletes that carry success (modules, courses, slides, tests, games, simulations, videos, course chapters, and course lessons), and on module, slide, and test updates, which carry success next to the resource. Browser clients can read all three: the Content API lists them in Access-Control-Expose-Headers.

TutorFlow records which keys still receive deprecated fields, and contacts the organizations behind those integrations before the sunset.

Checking your integration

• Search your code for .items, .totalCount, .total, and .success on Content API responses, and for a take query parameter, and move to the replacements.
• Log a warning when a response carries a Deprecation header, so a missed alias shows up in your own monitoring.
• Read the Changelog before each deploy of your integration.