INTEGRATION GUIDE · BETA · SOURCE CHECKED 16 NOV 2026

Migrate Discourse from the Perspective API (before 31 Dec 2026)

Perspective-shaped requests, independent scores. Change the connection, then validate the moderation decisions.

Google’s Perspective API notice gives 31 December 2026 as the shutdown date. Plan and test your migration before then.

1. Prepare a staging copy

Save the integration version, settings, current thresholds and old scores before changing providers. Create a Decision Models key in the dashboard; store it only on your server. Examples use environment variables, never real keys.

The plugin sends posts for toxicity scoring and uses the returned score for moderator flags or composer warnings (Discourse endpoint and request attributes). The host is hard-coded. Discourse staff now point users to AI + Automation workflows; consider that supported product direction before maintaining a fork. This patch path is for self-hosted installations where you control plugin code.

2. Change the endpoint and key

In a maintained fork of discourse-perspective-api, apply this one-line patch to lib/discourse_perspective.rb. Install that fork through your normal self-hosted Discourse plugin process and rebuild/restart as your deployment requires. In site settings replace perspective_google_api_key with the Decision Models key; the setting name remains historical.

-  GOOGLE_API_DOMAIN = "https://commentanalyzer.googleapis.com"
+  GOOGLE_API_DOMAIN = "https://moderation.decisionmodels.io"

There is no endpoint site setting in the inspected settings file. Hosted Discourse customers should use the workflow their hosting provider supports; this guide does not provide a hosted-plugin override.

Attributes and compatibility

The standard setting requests TOXICITY. The plugin’s “severe toxicity (experimental)” choice requests SEVERE_TOXICITY. TOXICITY has held-out English measurements; SEVERE_TOXICITY is experimental, not evaluated and uncalibrated.

Built-in and experimental attribute names

Built-in: TOXICITY, IDENTITY_ATTACK, INSULT, PROFANITY, THREAT. Built-in does not mean score parity with Perspective.

Experimental, not evaluated and uncalibrated: SEVERE_TOXICITY, SEXUALLY_EXPLICIT, FLIRTATION, SPAM, ATTACK_ON_AUTHOR, ATTACK_ON_COMMENTER, INCOHERENT, INFLAMMATORY, LIKELY_TO_REJECT, OBSCENE, UNSUBSTANTIAL. Responses identify requested experimental attributes in X-DM-Experimental-Attributes. Unknown attributes return 400. Check the current attribute and language documentation before enabling automatic actions.

Re-tune the thresholds

Discourse defaults defaults to perspective_flag_post_min_toxicity = 0.9 and perspective_notify_posting_min_toxicity = 0.85. The plugin defaults to disabled, and its composer notification toggle also defaults to disabled. Record your actual toggles as well as the numbers. Re-tune flagging and warning separately.

Use the migration tool with representative comments, their saved Perspective scores and optional human labels. Compare flag rates, flagged-set overlap and, where labels exist, precision and recall. Matching a flag rate does not guarantee the same flagged comments or accuracy. Tune each attribute and action separately; do not copy the old numbers into production without review.

3. Test and re-tune

With DM_MODERATION_KEY set privately, this smoke command should return HTTP 200 and a numeric attributeScores.TOXICITY.summaryScore.value between 0 and 1. It checks transport and response shape, not moderation quality.

curl --fail-with-body --max-time 15 \
  'https://moderation.decisionmodels.io/v1alpha1/comments:analyze' \
  -H "Authorization: Bearer $DM_MODERATION_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"comment":{"text":"Thank you for explaining."},"requestedAttributes":{"TOXICITY":{}},"doNotStore":true}'

On the rebuilt staging site, enable the intended checks, submit a new post and test the composer warning. Confirm a high-scoring sample reaches moderator flags. Test HTTP failures: the existing response parser can fall back to 0.0 on malformed data, so do not assume every error holds a post.

In staging, test benign, abusive, borderline, quoted and multilingual comments; compare actual queue or warning actions with human decisions. Also test invalid keys, untested-language warnings, 429 rate limits and a timeout. Keep a manual moderation fallback rather than interpreting a failed request as a safe score. Check limits and errors and plan quotas and request rates.

4. Roll out with a fallback

You own fork maintenance and update conflicts. The plugin has short timeouts (one-second connect, three-second read/write) and no network retry; validate latency and failure handling before enabling actions. Restore the original plugin revision and matching settings to roll back.

Keep the saved version and settings so you can reverse this change. Before Google’s shutdown, you can restore the Google endpoint together with its Google key and old thresholds if that service remains available to your account. After shutdown, use a tested alternative or manual review. Never send a Decision Models key to the Google host, or a Google key to Decision Models.

Shared gaps: scores come from an independent model; sentence-level span annotations are unavailable (one whole-text span only). Only PLAIN_TEXT is accepted. Valid explicit language hints are accepted and echoed. Untested hints or detected languages carry X-DM-Language-Untested. Tested languages: English (5 attributes) and German (offensive-language proxy only). This is not evidence of language quality. Suggested-score feedback is acknowledged but not stored or used to train the model. See the full API contract.

Source notes

These instructions follow the linked source revisions, inspected on 16 November 2026. Your installed release may differ. Patches and examples are migration recipes, not upstream endorsements or a claim of an end-to-end verified integration.

Discourse endpoint and request attributes · Discourse defaults · timeouts, score parsing and action comparisons