Developer and AI Agent Runbook

Use this runbook when you, or an AI coding agent working for you, write integration code, test scripts, SDK wrappers, or support diagnostics for the Content API. For a machine-readable description of every route, import the OpenAPI description.

The boundary

A Content API client never needs a platform key, a workspace id, an edit token, or a platform URL. If generated code reaches for one, it is on the wrong API.

Discovery

Never hard-code ids copied from screenshots, examples, or a database.

1. The key comes from Settings > Content API, as an environment variable.
2. GET /v1/content/credits confirms the key works.
3. GET /v1/content/classrooms lists the classrooms the key can use. Select one by name or slug from configuration, not by array position.
4. Resource ids come from create responses, lists, or expansion results.

Resource calls do not need an organization id. It is needed only for admin session routes.

Environment variables

Use these names, as the rest of these docs do:

Safe defaults

What to store

Smoke test

set -euo pipefail
 
curl -sSf "$TUTORFLOW_API_BASE_URL/v1/content/credits" -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY" > /dev/null
 
MODULE_ID="$(curl -sSf -X POST "$TUTORFLOW_API_BASE_URL/v1/content/classrooms/$CLASSROOM_ID/modules" \
  -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: module:smoke-test:v1" \
  -d '{ "title": "Content API smoke test", "content": "<p>Created by the Content API.</p>", "metadata": { "externalId": "smoke-test" } }' \
  | jq -er '.id')"
 
curl -sSf "$TUTORFLOW_API_BASE_URL/v1/content/classrooms/$CLASSROOM_ID/modules/$MODULE_ID" \
  -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY" > /dev/null
 
curl -sSf -X PATCH "$TUTORFLOW_API_BASE_URL/v1/content/classrooms/$CLASSROOM_ID/modules/$MODULE_ID" \
  -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Content API smoke test, updated" }' > /dev/null
 
curl -sSf -X DELETE "$TUTORFLOW_API_BASE_URL/v1/content/classrooms/$CLASSROOM_ID/modules/$MODULE_ID" \
  -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY" | jq -e '.deleted == true' > /dev/null
 
echo "smoke test passed"

Run the same create, read, update, and delete for every resource type the integration manages; the bodies are in Resources. The script fails fast on any non-2xx status and on an empty id.

Common mistakes

Before handing code to a customer

1. It discovers classrooms through the API and takes the key from the environment.
2. It uses only /v1/content/** and tf_content_ keys.
3. Every create and POST action sends a stable Idempotency-Key.
4. It stores TutorFlow ids next to the customer's ids.
5. It handles 400, 401, 402, 403, 404, 409, 413, 422, and 429 as in Errors.
6. Logs redact the key and the webhook secret.
7. A small real request has completed before larger batches run.