Compatibility Details
This page is for the cases where you need the exact detail about differences between the Perspective API and ours. It covers the two Perspective-compatible endpoints:
/v0.2/perspective-compat/analyse/v0.2/perspective-compat/suggestscore
Requests and Responses
| Item | Support | Notes |
|---|---|---|
| Perspective-style request format | Supported | Keeps the familiar request model |
| Perspective-style response format | Supported | Returned as closely as currently supported |
Authentication with X-User-Email and X-API-Key | Supported | Replace Perspective's query-string key |
| Canonical Perspective attributes | Supported | Core moderation attributes are supported |
| Google aliases and experimental names | Supported | Requested alias names are preserved in responses |
scoreThreshold | Supported | Applied per requested compat attribute |
scoreType=PROBABILITY | Supported | A 0 to 1 score where higher means more of the requested attribute |
Other scoreType values | Unsupported | Rejected deliberately rather than guessed |
| Google-style error body | Supported | Every error on both endpoints uses {"error": {"code", "message", "status"}}, with status a google.rpc.Code name |
| Scoring temporarily unavailable | HTTP 503 | Google-style UNAVAILABLE error body; retry after a few seconds, or the Retry-After interval if given |
Error Statuses
Both endpoints return the HTTP status below, with the Google-style body. error.code repeats the HTTP status; error.status is the google.rpc.Code name Perspective clients already branch on.
| HTTP status | error.status | Meaning | What to do |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | The request is malformed, missing the comment, or asks for a scoreType other than PROBABILITY | Fix the request; retrying it unchanged fails again |
| 401 | UNAUTHENTICATED | X-User-Email or X-API-Key is missing or wrong | Check your credentials |
| 402 | FAILED_PRECONDITION | Your account's credit balance does not cover this call | Add funds, then retry. Do not retry automatically |
| 413 | INVALID_ARGUMENT | The body is over 1 MB, or was sent with chunked transfer encoding | Send a smaller body with a Content-Length header |
| 429 | RESOURCE_EXHAUSTED | suggestscore only: too many score suggestions | Retry after the number of seconds given in the message |
| 503 | UNAVAILABLE | Scoring is temporarily unavailable | Retry after a few seconds, or the Retry-After interval if given |
A method other than POST returns HTTP 405 with error.status UNIMPLEMENTED. A server fault returns HTTP 500 with INTERNAL.
If you are not sure how to read PROBABILITY, summaryScore, or spanScores, see Perspective Score Types.
Spans and Languages
| Item | Support | Notes |
|---|---|---|
spanAnnotations | Supported | spanScores are included only when requested. Spans are whole sentences, given for attributes scoring 0.15 or higher, for comments of up to 20 sentences |
| Span offsets | Supported | UTF-16 code units on escaped output text |
languages when supplied | Supported | Preserved in the response |
Language detection when languages is omitted | Not claimed | Respectify does not detect languages |
If your interface uses spans directly, test with emoji, quotes, ampersands, and text that looks like HTML. Returned span text is escaped for safe display, and the offsets line up with that escaped text.
If you rely on language fields, the important rule is simple: Respectify preserves languages when you send them, and does not claim detection when you do not.
Context and Score Corrections
| Item | Support | Notes |
|---|---|---|
context.entries | Accepted | Text entries accepted, but not currently used in scoring: the comment is scored on its own |
context.articleAndParentComment | Accepted | Accepted, but not currently used in scoring |
| HTML text entries | Supported | type: HTML is normalised to text |
suggestscore summary scores | Supported | summaryScore.value accepted |
suggestscore span scores | Partially validated | Accepted and validated for score type, but stored correction remains summary-score based |
Request Metadata and Storage
| Item | Support | Notes |
|---|---|---|
doNotStore | Accepted | Analyse traffic is currently treated as though doNotStore were always true, because it is not retained for training |
sessionId | Accepted | Logged for traceability, does not affect scoring |
communityId | Accepted | Logged for traceability, does not affect scoring |
dropUnsupportedAttributes | Accepted | Unsupported attributes are already ignored in common compat flows |
Feedback sent through suggestscore is stored intentionally, ie retained. That is the purpose of the correction endpoint.
We retain logs of each call (that it was made, which account, which endpoint, what it cost, and related info) which are required for our records, billing, etc, but we do not retain the content of what was scored - the text itself.
- Migration steps
- Attribute mapping
- or back to the Perspective Compatibility Overview