A game is a playable web page built from a practice objective. Games use the same operations and credit prices as the TutorFlow editor. Every route is under /v1/content/classrooms/{classroomId}/games and takes a tf_content_ key.

Planning, building, revising, restoring, and sharing work the same way for games and simulations, and are described once in Generation: Brief, Build, Revise. This page covers what is specific to games. The full route list is in the API Reference.

The game object

Create, read, update, and restore return the same shape. content appears only on GET /games/{gameId}.

Field	Notes
`id`	Use as `{gameId}` on later calls.
`classroomId`	The classroom the game belongs to.
`title`, `description`	Display text. `description` may be `null`. While `title` still equals `metadata.topic`, a generated brief replaces it with the game's own name.
`visibility`	`PRIVATE` or `PUBLIC`. A public, built game opens at its play page (`publicUrl`) without an account.
`slug`	A short label TutorFlow assigns. It is not part of any link.
`metadata`	An object you own. The keys in Metadata that shapes the plan feed the brief; other keys are stored untouched, except that sending `language` also stores `isLanguageChosen: true`.
`brief`	The plan the build reads. `null` until a brief is generated or written. See The brief.
`contentKey`	Storage reference of the version being served. An opaque identifier, not a URL. `null` until the first build.
`contentVersion`	The version being served. `0` until the first build, then incremented by every build, revision, and restore.
`buildHistory`	One entry per version: `version`, `contentKey` (opaque), `createdAt`, `source` (`build`, `revision`, or `restore`), `note` with the revision feedback when there was one, and `restoredFromVersion` on a restore. A save from the visual editor in TutorFlow also adds a `revision` entry, with `note: "Visual editor"` and no feedback; it cost no credits.
`thumbnail`	Storage reference of a capture of the opening screen, or `null`. An opaque identifier, not a URL.
`content`	The built game as one complete HTML document, or `null` before the first build. Only on `GET /games/{gameId}`.
`createdAt`, `updatedAt`	Timestamps. Sort the list by `updatedAt` to find recent changes.
`editorUrl`	The game in the TutorFlow editor, for a person signed in to TutorFlow as an admin of the organization. `null` in the sandbox classroom.
`publicUrl`	The play page, `https://tutorflow.io/games/play/{gameId}`, while the game is `PUBLIC` and built. `null` otherwise and in the sandbox classroom.

content is the whole page and can be large, so lists never include it. To show a game to people, set it to PUBLIC and send publicUrl, or serve the HTML from content yourself. See Check and share what you made.

The brief

A generated brief has these fields. Write your own with PATCH /games/{gameId} and a brief object to skip the priced brief call.

Field	Notes
`title`	Short, concrete title for the game.
`pitch`	One sentence on what playing it is like.
`coreLoop`	The action the player repeats.
`mechanics`	Two to five rules or devices the game is built from.
`levels`	Two to six entries of `name`, `goal`, and `twist`.
`winCondition`, `failCondition`	What ends a run either way.
`controls`	How it is played, by keyboard and by touch.

Metadata that shapes the plan

The TutorFlow create wizard stores its answers on metadata, and the brief reads the same keys. All are optional. PATCH merges metadata: keys you send replace their old values, and keys you leave out stay.

Key	Values	Notes
`topic`	Free text	What the game teaches. Falls back to `title`.
`audience`	Free text	Who plays it.
`objectiveFocus`	Free text	The skill a round should exercise.
`mechanic`	Free text	A mechanic to build around, if you have one in mind.
`dimension`	`2d` or `3d`	Defaults to `2d`. It does not change the price.
`persistence`	`session` or `local`	Whether progress survives a reload. Defaults to `session`.
`playLength`	`short`, `standard`, or `deep`	Defaults to `standard`.
`visualStyle`	Free text	Art direction for the page.
`language`	Language name or code	Language of on-screen text. When unset, the plan infers it from `topic`, `objectiveFocus`, and `referenceMarkdown`; set it to be sure.
`referenceMarkdown`	Markdown	Your own material to ground the plan. `POST /brief` can override it per call.

Create a game

title and visibility are required. Create it PRIVATE, and set it PUBLIC once the build has been checked (you read content, or a person opens editorUrl).

bash

curl -X POST "$TUTORFLOW_API_BASE_URL/v1/content/classrooms/$CLASSROOM_ID/games" \
  -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: game:fractions-run:v1" \
  -d '{
    "title": "Fractions run",
    "description": "Practice comparing fractions under time pressure.",
    "visibility": "PRIVATE",
    "metadata": {
      "topic": "Comparing fractions with unlike denominators",
      "audience": "Grade 5",
      "objectiveFocus": "Decide which of two fractions is larger",
      "playLength": "short",
      "language": "en",
      "externalId": "game:fractions-run"
    }
  }'

The response is 201 with the game object, contentVersion: 0, brief: null.

List games

HTTP

GET /v1/content/classrooms/{classroomId}/games?page=1&limit=20&field=updatedAt&order=DESC&search=fraction
Authorization: Bearer tf_content_...

Parameter	Default	Notes
`page`	`1`	1-based.
`limit`	`20`	Values above `100` are clamped to `100`. `take` is a deprecated alias.
`field`	`createdAt`	`title`, `createdAt`, or `updatedAt`. Anything else returns `422` with `error.allowedValues`.
`order`	`DESC`	`ASC` or `DESC`. Ties break on `id`.
`search`		Case-insensitive substring of `title`.
`updatedSince`		ISO 8601 date-time. Only games updated at or after it.

The response is the list envelope with game objects without content. The same parameters work on every resource list; see List pages.

Update a game

PATCH /games/{gameId} is partial. It accepts title, description, visibility, brief, thumbnail, and metadata, and returns 200 with the updated game. description cannot be set to null (422); send an empty string. A new thumbnail must be a storage key under the classroom, for example from an upload. contentKey and contentVersion belong to the build pipeline and cannot be set.

Other routes

The rest of the game routes are listed in the API Reference: DELETE /games/{gameId}, POST .../brief, POST .../build, POST .../revise, GET .../run, and POST .../versions/{version}/restore (takes Idempotency-Key). The brief, build, and revise steps are described in Generation. Single reads and PATCH carry an ETag; send If-Match on PATCH to avoid overwriting a change made elsewhere. See Concurrency.

Games over the Content API