Generator Release 2.0.0 and Upgrade Guide

New Features

• Model Context Protocol (MCP) Support: Generator now includes native support for the Model Context Protocol (MCP). This enables Large Language Models (LLM applications, AI agents, and orchestration frameworks) to directly interface with Generator as a standardized context provider and tool server.
• Enhanced Content Structure Schema: The course content structure schema has been expanded to provide fine-grained detail regarding course hierarchy. New formats include:
  • TREE: Returns a more in depth representation of the course's structure via nested json objects
  • NODES: Returns a more in depth representation of the course's structure via a flat list of objects with parent and child ids
  • MARKDOWN: Returns the entire course's text as plain text, formatted in markdown

Breaking Changes

Core API & ID Rules

• Restricted Characters in Resource "id" Fields: All API resource `id` values now enforce strict character validation. The following characters are prohibited:
  • <, >, newline (\n), tab (\t), forward slash (/), backslash (\), colon (:), double quote ("), question mark (?), and asterisk (*).
  • If your instance currently contains resources with IDs containing any of these characters, contact the Rustici Support Team prior to running the upgrade.
• Normalized ISO 8601 Datetime Formatting: All datetimes returned across the API now explicitly include the UTC timezone designator in the format YYYY-MM-DDTHH:MM:SS.sssZ (e.g., 2026-10-06T14:19:32.000Z).
• Webhook Payload Versioning: The body_version field inside outgoing webhook notification payloads has been bumped to `2.0.0` to accommodate the normalized datetime output.
• Interactions Schema: The schema previously used to represent interactions has been updated to support localized text objects across content text fields. See the updated Content Details documentation for structure definitions.
  • Affected Endpoints: /api/v1/content/<id>/, /api/v1/content/<id>/version/<version>/, and interaction payloads embedded in the extract content text.

Authentication & Token Behavior

• Timestamp Nonce Enforcement: Token creation requests now require a timestamp nonce in the request body to prevent replay attacks.
  • Refer to the API Authentication documentation for request details.
  • Self-Hosters: To opt out, set the environment variable SECURITY__NONCE_REQUIRED=False
  • Managed Hosting: Contact Rustici Support to modify this setting for your instance.
• Expired Token Response Status: Requests made with expired bearer tokens now return an HTTP 401 Unauthorized status code instead of HTTP 403 Forbidden.

Deprecated Properties Removed

• Taxonomy Import Schema: The legacy csv_skill_col_name field in the taxonomy import job payload has been renamed to csv_col_name.

• Generation Job Schema: The standalone fields_to_generate array in generation job request bodies has been restructured under a parent object:

  // Legacy (v1.x)
  {
    "fields_to_generate": ["field_a", "field_b"]
  }
  
  // Updated (v2.x)
  {
    "field_generation": {
      "fields_to_generate": ["field_a", "field_b"]
    }
  }

Self-Hosted Changes

Required Configuration Key

• The previously-optional environment variable SECURITY__HEALTH_CHECK_API_KEY is now mandatory.
  • You must configure this variable with a secure, randomly generated secret string.
  • Requests to the system health endpoint (GET /api/v1/health/check_up) must pass this key to authenticate health checks.
    • Use the /api/v1/health/check_up endpoint to verify service health and its connections to other required services.
    • Example: curl -H "X-API-Key: your-secure-api-key-here" http://localhost/api/v1/health/check_up

Schema Migration Command

• The included database management tool upgrade_schema.sh now requires an explicit operational argument rather than automatically assuming if an installation or an upgrade is being requested:

  # Executing an initial installation:
  ./upgrade_schema.sh install
  
  # Upgrading an existing database schema:
  ./upgrade_schema.sh upgrade

Upgrade & Database Migration Notes

Service Downtime Requirements

• Database migrations in v2.0 require a few minutes of scheduled downtime:
  • Managed Hosting: The Rustici hosting team will coordinate directly with primary contacts to schedule the maintenance window.
  • Self-Hosted: Technical administrators should coordinate downtime windows with internal operations and active user groups.

Recommended Self-Hosting Upgrade Workflow 

• Because version 2.0 introduces changes to both the API and requires a database schema migration, perform the following verification steps prior to production deployment:

  1. Backup: Create a fresh snapshot/backup of your production database.
  2. Stage: Restore the backup to an isolated staging or pre-production environment.
  3. Migrate: Run `./upgrade_schema.sh upgrade` against the restored staging database.
  4. Smoke Test: Validate API workflows, webhook listeners, and third-party integrations against the staging instance prior to upgrading production.