Perspective API Retirement: Timeline, Impact, and a Migration Plan

Google's Perspective API has powered toxicity scoring for comment systems since 2017. That run is ending: Google announced the Perspective API retirement with a 2026 shutdown window, and teams that rely on comments:analyze need a plan.

This post covers what is retiring, what breaks, and a concrete migration path so your moderation keeps working after the shutdown.

What is being retired

Perspective API is being sunset as a public product. When the retirement completes:

• The commentanalyzer.googleapis.com/v1alpha1/comments:analyze endpoint stops accepting requests
• Attribute scores (TOXICITY, SEVERE_TOXICITY, INSULT, THREAT, IDENTITY_ATTACK, PROFANITY, SEXUALLY_EXPLICIT) stop being returned
• API keys tied to the project lose access
• No direct Google successor has been announced

If your product gates comments, chat, or forum posts on Perspective scores, the shutdown takes that gating down with it - unless you migrate first.

Timeline to plan around

Google's announcements give a 2026 window rather than a single hard date. The practical timeline for your team:

• Now - Inventory every call site that depends on Perspective attributes
• Before your last pre-shutdown release - Swap the endpoint and remap categories behind a single wrapper
• Before the shutdown date - Turn off the Perspective integration entirely and verify thresholds against the new provider
• After shutdown - Keep your category mapping documented for future policy audits

The mistake to avoid is migrating category logic in a hurry after the endpoint stops responding.

What breaks vs what keeps working

// This stops working when the retirement completes
const url = 'https://commentanalyzer.googleapis.com/v1alpha1/comments:analyze';

const res = await fetch(url, {
method: 'POST',
body: JSON.stringify({
  comment: { text: userComment },
  requestedAttributes: { TOXICITY: {}, THREAT: {} },
}),
});

const scores = await res.json(); // { attributeScores: {...} }

Your policy logic (thresholds, actions, review queues) keeps working - it just needs a new source of decisions. That is the part worth protecting: remap once, keep the rest.

Migration plan in four steps

1. Wrap every Perspective call in one function

Do not scatter the endpoint across your codebase. A single moderateText() wrapper means one swap migrates your entire product.

2. Map Perspective attributes to Vettly categories

// Perspective attribute -> Vettly category
const categoryMap: Record<string, string> = {
TOXICITY: 'harassment',
SEVERE_TOXICITY: 'harassment',   // lower threshold, e.g. 0.3-0.5
IDENTITY_ATTACK: 'hate_speech',
INSULT: 'harassment',
PROFANITY: 'profanity',
THREAT: 'violence',
SEXUALLY_EXPLICIT: 'sexual',
};

3. Replace the endpoint with Vettly's /v1/check

import { Vettly } from '@vettly/sdk';

const vettly = new Vettly(process.env.VETTLY_API_KEY);

async function moderateText(text: string) {
const result = await vettly.check({
  content: text,
  contentType: 'text',
  policyId: 'moderate',
});

return {
  action: result.action, // allow | review | block
  categories: result.categories,
  decisionId: result.decisionId,
};
}

4. Tune thresholds once, then add what Perspective never had

With decisions coming from Vettly you get images, video, webhooks, dashboards, and appeals through the same integration - the exact features the retirement forces you to think about anyway.

Why this matters for compliance

Perspective never provided reporting, blocking, or audit trails. If you built those yourself, they keep working. If you deferred them, the retirement is a forcing function: Apple App Store Guideline 1.2 and Google Play's UGC policy both require filtering, reporting, blocking, and an audit trail - not just a toxicity score.