Developer and AI Agent Runbook

Use this runbook when a developer or AI coding agent is writing integration code, test scripts, SDK wrappers, or support diagnostics for Content Integration.

Non-negotiable boundary

Content Integration is the API surface for content that people create, review, or manage in TutorFlow UI.

Do not mix these surfaces. A Content API client should never require an Agent Platform ownership id, platform key, edit token, or Platform public URL.

Discovery sequence

Never ask a customer to guess ids from a screenshot or copy ids from an internal database.

1. Sign in as a TutorFlow admin and create tutorflow-admin.cookies.
2. Call GET /v1/content/organizations with the admin session cookie.
3. Create a tf_content_ key for the selected organization.
4. Call GET /v1/content/classrooms with the tf_content_ bearer key.
5. Use the returned classroom id for expansion and resource CRUD.

Minimal environment variables

Discover these values through the API. Do not ask the customer to find them in screenshots or internal admin tools.

export TUTORFLOW_API_BASE_URL="https://api.tutorflow.io"
 
export TUTORFLOW_CONTENT_API_KEY="$(printf '%s' "$KEY_RESPONSE" | jq -r '.apiKey')"
 
export TUTORFLOW_CLASSROOM_ID="$(curl -sS "$TUTORFLOW_API_BASE_URL/v1/content/classrooms" \
  -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY" | jq -r '.[0].id')"

Do not introduce an organization-id environment variable as a prerequisite for bearer-key resource calls. Organization id is only needed while an admin creates or manages keys and webhooks.

Safe request defaults

Use these defaults in generated clients and examples:

Good idempotency key patterns:

module:{externalModuleId}:{version}
course:{externalCourseId}:{version}
video:{externalVideoId}:{version}
slides:{externalDeckId}:{version}
test:{externalAssessmentId}:{version}
expansion:{externalContentGroupId}:{version}

Response handling contract

Store these values after every successful create or expansion result:

Do not store full tf_content_ keys in logs, analytics events, crash reports, or generated code comments.

Smoke test script outline

The smallest smoke test can use one module. A production-ready integration test must also exercise the resource types the customer plans to manage.

set -euo pipefail
 
curl -sS "$TUTORFLOW_API_BASE_URL/v1/content/classrooms" \
  -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY"
 
MODULE_ID="$(curl -sS -X POST "$TUTORFLOW_API_BASE_URL/v1/content/classrooms/$TUTORFLOW_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",
    "type": "markdown",
    "content": "<h2>Smoke test</h2><p>This module was created by the Content API.</p>",
    "metadata": {
      "externalId": "module:smoke-test"
    }
  }' | jq -r '.id')"
 
curl -sS "$TUTORFLOW_API_BASE_URL/v1/content/classrooms/$TUTORFLOW_CLASSROOM_ID/modules/$MODULE_ID" \
  -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY"
 
curl -sS -X PATCH "$TUTORFLOW_API_BASE_URL/v1/content/classrooms/$TUTORFLOW_CLASSROOM_ID/modules/$MODULE_ID" \
  -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Content API smoke test updated"
  }'
 
curl -sS -X DELETE "$TUTORFLOW_API_BASE_URL/v1/content/classrooms/$TUTORFLOW_CLASSROOM_ID/modules/$MODULE_ID" \
  -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY"

Full CRUD coverage matrix

For a customer integration that controls TutorFlow UI content, verify every required resource type before handoff.

Use Content Resource API for complete request bodies. A test script should fail fast when any returned id is empty or null.

Common AI agent mistakes

Pre-handoff checklist

Before handing integration code to a customer, verify:

1. The script discovers organization and classroom ids through the API.
2. The script uses only tf_content_ keys for /v1/content/**.
3. No Agent Platform ownership id, platform API key, edit token, or Platform URL appears in generated customer code or support notes.
4. Create requests send stable idempotency keys.
5. The script stores returned TutorFlow ids next to external ids.
6. The script handles 400, 401, 403, 404, 409, and 429 responses.
7. Logs redact the full bearer token.
8. A small pilot payload completes before larger production payloads are sent.