Skip to main content
Perspective API gives you toxicity scores you threshold in your own code. Moderation API returns the same scores for the same categories, so that part of your integration carries over. It also runs many more policies, accepts images, video, and audio, and includes a review queue, a rules engine, and custom models. None of that is needed to migrate. This guide shows how to replace the Perspective call, where each field and attribute goes, and how to carry your thresholds across.
Google Jigsaw has announced that Perspective API will no longer be in service after 2026. Existing integrations keep working until then, but new usage and quota increases are no longer approved.
You don’t have to do this yourself. Send us the code that calls Perspective and we’ll write the migration for you, validate the scores against your historical data, and stay on call through cutover. Book a migration call or email support@moderationapi.com.

Hand it to a coding agent

This guide is available as Markdown, so a coding agent working in your repository can do the migration for you. Paste the prompt below into Claude Code, Cursor, Codex, or whatever agent you use, and it will read the guide and rewrite your Perspective call sites.
Prompt
Use the Copy page option at the top of this page if your agent can’t fetch URLs.

At a glance


Before you start

Create a project in the dashboard and copy its API key. Store it as MODAPI_SECRET_KEY, which is the environment variable the official SDKs read. See Authentication for details.

Enable the policies that match your attributes

With Perspective you list the attributes you want in every request. With Moderation API the policies are configured once, on the project’s channel, and every request runs all of them. Open Policies in the dashboard and enable the policies that correspond to the attributes you request today. Use the attribute mapping table below to find each one.

Swap the request

Replace the Perspective call with a call to /moderate. Pick your language below, then switch between the Perspective and Moderation API tabs to compare the two calls.
Rather not touch the call sites yourself? Send us your code and we’ll write the migration for you.

Read the response

Perspective returns one score per requested attribute. Moderation API returns one entry per enabled policy in the policies array, plus an overall evaluation and a recommendation you can act on directly.
Perspective response
Moderation API response (trimmed)
See Understanding API responses for the full response shape, and the field mapping below for every field.

If you rely on the scores

Most Perspective integrations read summaryScore.value for each attribute and compare it against a threshold in their own code, often a different one per attribute. You can keep doing exactly that. Each policy in the policies array carries a probability between 0 and 1, the same range Perspective uses. Build the same score object you have today from the mapped policies, and your downstream logic doesn’t need to change:
Perspective
Moderation API
The range is the same, but the models are not. A comment Perspective scored 0.72 for TOXICITY won’t necessarily score 0.72 for toxicity, so treat the thresholds you tuned for Perspective as a starting point. Run both APIs on the same traffic before you cut over. See Validate before you cut over.
probability is always returned, even below the threshold. Perspective’s scoreThreshold option, which drops scores under a cutoff, has no equivalent. Filter on your side if you need it.

Use the dashboard to find the right thresholds

You can set threshold values in the dashboard and see what they would do before committing to them. Each policy has a Threshold tab under Policies in your project, showing a histogram of the confidence scores from your recent traffic. As you move the slider, the bars to the right are what would be flagged and the bars to the left what wouldn’t, with counts for how many recent items would flip sides.
Policy threshold slider with histogram and would-flag / would-not-flag counts
This works well as a calibration tool even if you keep your thresholds in code: send real traffic, find the cutoff on the histogram that matches the behavior you had with Perspective, then copy that number into your integration. See Per-policy thresholds.
We can also calibrate the thresholds for you. Share a sample of content with your Perspective scores or your moderators’ decisions, and we’ll run the comparison against Moderation API and hand back the threshold per policy that best reproduces your current behavior. Get in touch to set it up.

Or let the API make the decision

Once the thresholds live in the dashboard, you can drop the score comparison entirely. The API sets flagged on each policy, combines everything into a severity_score, and returns a recommendation.action of allow, review, or reject.
Thresholds become something you tune against real data instead of a constant in your code, and content rules cover the cases a single score can’t express, like “reject toxicity_severe from new accounts, review it from everyone else.”

Validate before you cut over

Run both APIs side by side on live traffic before you remove Perspective:
  1. Enable dry-run in your project settings. The API still analyzes and stores everything, but flagged is always false, so nothing is blocked while you compare.
  2. Send your production content to /moderate alongside your existing Perspective call and compare scores on the content you already have decisions for.
  3. Adjust per-policy thresholds using the histogram on each policy’s Threshold tab, then turn dry-run off.
Dry-run mode: If you want to analyze production data but don't want to block content, enable "dry-run" in your project settings.
With dry-run enabled, the API still analyzes content but it always returns flagged: false - yet content still shows in the review queue. This way you can implement your moderation workflows and start testing your project configuration without actually blocking content.
If you’d rather test one policy at a time, shadow flagging lets a policy score traffic without affecting flagged.

Map request and response fields

Request

Response

Sending feedback

Perspective’s comments:suggestscore method lets you report a score you disagree with. Moderation API has no equivalent call. Instead, decisions your moderators make in the review queue are stored as cases in the casebook, which applies those rulings to similar content automatically. You can resolve items programmatically with the resolve a queue item endpoint.

Map attributes to policies

Each Perspective attribute maps to one Moderation API policy. Enable the policy in the dashboard, then read its entry in the policies array using the id below.

Bridging attributes

Perspective’s experimental bridging attributes score constructive qualities rather than harms. Moderation API doesn’t have equivalents yet.
If you rely on any attribute marked WIP, let us know. It helps us prioritize.
Once you’ve migrated, consider enabling policies Perspective never offered:

Self-harm

Self-harm, suicide, and eating-disorder content, which often deserves a support resource rather than a rejection.

Personal information

Detect and mask emails, phone numbers, and addresses.

Phishing and code abuse

Scam messages, prompt injection, and malicious code.

Guidelines

Write your own rules in plain language and get them back as policies.

Other differences worth knowing

  • Rate limits. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers, and a 429 includes Retry-After. See Rate limits.
  • Partial failures. If one policy fails, the rest still return. Check meta.status for partial_success and read the errors array. See Handle errors.
  • Mixed content. Send a profile or listing with several fields as a single object and get flagged_fields back per policy. See Object.
  • Review queue. Every stored submission is available for human review without any extra integration work. See Review.