Simulations over the Content API

Simulations are reachable from the Content API with the same operations the admin UI has, and at the same credit cost. The API routes through the very services the UI calls, so nothing about access, validation, or pricing differs between the two.

All routes live under /v1/content/classrooms/{classroomId}/simulations and take a tf_content_ key. Discover the classroom id with GET /v1/content/classrooms first.

What a simulation is

A model a learner perturbs. There is no winning, no losing, and no score; the learner moves controls and reads what changes. If you want something with a score, you want Games instead.

Resource operations

None of these consume AI Credits. POST /simulations and the restore action honour the Idempotency-Key header like the other content resources: a retry with the same key and body returns the response made the first time, and the same key with a different body returns 409.

The simulation object

Every read, create, update, and restore returns the same shape. content appears only on GET /simulations/{simulationId}.

A tuning entry records a change made in the TutorFlow editor to a control's range, step, or starting value. The document was patched in place rather than regenerated, so it cost no credits. There is no Content API call that produces one; you will only see it on simulations an educator has also worked on.

content is the whole page and can be large. GET /simulations never includes it. List responses carry metadata only, so paging through a classroom stays cheap.

The brief

brief is the most useful thing to read if you want to know what a simulation actually does without parsing its HTML, and the place to catch a wrong model before paying for a build. A generated brief has these fields:

You can replace the brief with PATCH /simulations/{simulationId} and a brief object, so an integration that already knows the model it wants can skip the priced brief call.

Creating a simulation

title and visibility are required. Keep new simulations PRIVATE until a person has opened the build.

curl -X POST "$TUTORFLOW_API_BASE_URL/v1/content/classrooms/$TUTORFLOW_CLASSROOM_ID/simulations" \
  -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: simulation:compound-interest:v1" \
  -d '{
    "title": "Compound interest",
    "description": "See how rate and time change a balance.",
    "visibility": "PRIVATE",
    "metadata": {
      "topic": "Compound interest on a savings balance",
      "audience": "First-year finance",
      "objectiveFocus": "Why doubling the time matters more than doubling the rate",
      "theme": "auto",
      "language": "en",
      "externalId": "simulation:compound-interest"
    }
  }'

Metadata that shapes the plan

The admin UI's create screen stores its answers on metadata, and the brief reads the same keys. Set them on create or with a later PATCH. All are optional.

PATCH merges metadata: keys you send replace their old values, and keys you leave out stay as they were.

Listing simulations

GET /v1/content/classrooms/{classroomId}/simulations?page=1&limit=20&order=DESC&field=updatedAt&subject=finance

The response is { "items": [...], "totalCount": n }, with the same fields as the object above minus content.

Updating a simulation

PATCH /simulations/{simulationId} is partial. Fields omitted keep their values. It accepts title, description, visibility, brief, and metadata. It cannot set subject, representation, contentKey, or contentVersion; those belong to the planner and the build pipeline.

Generation

Building a simulation is three steps, and each is its own call. They are separate because the plan is cheap and the build is not: reading a plan and rejecting it should not cost what building it costs.

These are the same prices the admin UI pays, drawn from the organization's AI Credit balance. Check the balance with GET /v1/content/credits before a batch. A credit is charged only after the new version is stored; a build that fails costs nothing.

The planner decides between 2D and 3D when it writes the brief, so the build price is not known until the brief exists. Read representation on the simulation after brief-done: 2d-canvas builds and revises at 15, 3d-three at 20. A 3D page loads a three.js runtime, which is why it costs more to produce.

POST /simulations/{simulationId}/brief accepts an optional referenceMarkdown body field to ground the plan in your own material. The brief also settles subject and representation on the simulation. POST /simulations/{simulationId}/build takes no body. POST /simulations/{simulationId}/revise takes a feedback field of 1 to 2000 characters describing the change in plain language, the same way the chat panel in the editor does. The feedback is kept, truncated to 200 characters, as the note on the resulting history entry.

These three stream

The generation routes respond with text/event-stream, not a JSON body. Read them as Server-Sent Events. Each event has an event name and a JSON data line, and the response ends after the terminal event.

event: progress
data: {"stage":"writing"}
 
event: progress
data: {"stage":"checking"}
 
event: build-done
data: {"contentKey":"classrooms/.../content/2.html","contentVersion":2,"thumbnail":"classrooms/.../thumbnail/2.png"}

Exactly one of brief-done, build-done, or error ends a stream.

Errors before and during the stream

The classroom, the simulation, its readiness, and the credit balance are all checked before the stream opens. Those failures come back as the normal JSON error envelope, not as events:

Once the stream has opened, the HTTP status is 200 whatever happens next, and a failure arrives as an error event.

Disconnecting aborts the work. If your client hangs up mid-build, the model call stops rather than running to completion unread, and nothing is charged. That also means a client timeout shorter than a build will cancel the build. Builds take minutes, not seconds, so set the timeout on these three calls with the build duration in mind rather than reusing the default you use for CRUD.

These three routes do not take Idempotency-Key. Retrying a build that already streamed build-done builds and charges again.

Restoring a version

POST /v1/content/classrooms/{classroomId}/simulations/{simulationId}/versions/{version}/restore
Idempotency-Key: simulation:{simulationId}:restore:3:v1

{version} is a version number from buildHistory. Restoring runs no model and charges nothing. It copies the chosen version forward as the newest one rather than rewinding, so a restore is itself reversible and nothing an educator made is lost. The response is the simulation with contentVersion incremented and a new history entry whose source is restore and whose restoredFromVersion names the version you chose.

An unknown version returns 404 with content_not_found. Send an Idempotency-Key: without one, a retried restore appends a second identical version.

Sharing and deleting

Set visibility to PUBLIC with a PATCH when the simulation is ready to share. It then opens at:

https://tutorflow.io/simulations/play/{simulationId}

That link needs no account. While the simulation is PRIVATE the link returns 404 to everyone, including its own classroom.

DELETE /simulations/{simulationId} soft-deletes the simulation and returns it. Later reads return 404 with content_not_found, and the play link stops working.

A typical run

1. POST /simulations with a title, visibility: "PRIVATE", and the metadata keys above. Keep the returned id.
2. POST /simulations/{simulationId}/brief. Read the plan from the brief-done event.
3. Inspect brief, especially model and controls. If the model is wrong, PATCH the metadata or brief, or ask for another brief. This is the cheap point to change your mind, and a simulation that computes the wrong thing is the failure this content type is most prone to.
4. POST /simulations/{simulationId}/build. Wait for build-done.
5. GET /simulations/{simulationId} to read the built document and its version history.
6. POST /simulations/{simulationId}/revise with feedback if something needs changing, or restore an earlier version if the revision made it worse.
7. PATCH /simulations/{simulationId} with visibility: "PUBLIC" once a person has opened it, and hand out its link.

What the build guarantees

Every generated version is checked before it is stored. Beyond validating the page, TutorFlow runs the simulation and drives each declared control from one end of its range to the other, watching whether the drawing actually changes. A version whose sliders move and whose picture does not is rebuilt rather than returned, because that failure passes every static rule and is useless in a classroom. If the rebuild fails too, the stream ends with an error event that lists the violations, and nothing is charged.

That check confirms the simulation responds. It does not check that the arithmetic is right, and it does not judge whether the subject or the difficulty suits a particular class. An integration that publishes automatically is publishing something no person has opened. Read the brief at minimum, and open the built document before it reaches learners.

Related guides

• Content Integration Overview
• Content API Key Management
• Content Integration Errors
• Games over the Content API