Perspective Compatibility Analyse

Accept a Google Perspective-style analyse request and return a Google-style response, while translating onto Respectify's scoring pipeline.

This endpoint is intended for easier migration from raw Perspective HTTP integrations. It preserves Google's wire shape as closely as currently supported, but it is not a claim of full behavioural parity.

Supported today: canonical Perspective attributes, preserved alias names, scoreThreshold, spanAnnotations, HTML text entries, and explicit languages when supplied.

Current limitations: only PROBABILITY score types are supported. In practice, that means 0 to 1 scores where higher values mean more of the requested attribute. Other score types are rejected. Respectify does not claim language detection when languages is omitted; compatibility responses fall back to the default English-oriented moderation context instead. doNotStore is accepted; in practice, analyse traffic is currently treated as though doNotStore were always true, because it is not retained for training. sessionId and communityId are accepted as request metadata for traceability, but they do not change scoring behaviour. dropUnsupportedAttributes is accepted, and current compat handling is already permissive in common flows.

How scores are produced: by Respectify's dedicated scoring model alone, on the comment text itself; scores are not rescaled afterwards. Span scores are one per sentence, for attributes whose summary score is 0.15 or higher, on comments of up to 20 sentences. Context entries are accepted but do not currently change the scores.

When scoring is unavailable: the endpoint returns HTTP 503 with a Google-style UNAVAILABLE error, rather than a guessed or partial result. Retry after a few seconds.

Header Parameters
X-User-Email email — REQUIRED Account email address, for authentication
X-API-Key string — REQUIRED API key owned by the user (email), for authentication

Request Body — REQUIRED
comment — REQUIRED Perspective-style comment input. String entries and {text, type} objects are accepted. HTML entries are normalised to text.
requestedAttributes object Google-style requested attribute map, for example { "TOXICITY": {}, "INSULT": {} }.
context object entries undefined[] articleAndParentComment object article parentComment
spanAnnotations boolean When true, include Google-style spanScores in the response.
languages string[] Optional list of requested languages. Preserved in the response when supplied.
clientToken string Opaque caller token echoed back in the response.
doNotStore boolean Accepted for compatibility. Respectify does not currently use analyse traffic for training, so this flag does not change today's scoring path.
sessionId string Accepted for compatibility as request metadata for traceability. Does not affect scoring behaviour.
communityId string Accepted for compatibility as request metadata for traceability. Does not affect scoring behaviour.
dropUnsupportedAttributes boolean Accepted for compatibility. Current compat handling is already permissive and ignores unsupported attributes in common flows.

Responses
200 Google-style compatibility response Schema — OPTIONAL attributeScores object — OPTIONAL languages string[] — OPTIONAL detectedLanguages string[] — OPTIONAL Present only if Respectify actually detected a language. Omitted when no detection was performed. clientToken string — OPTIONAL
400 Invalid request, including unsupported non-PROBABILITY score types. The request must change before it is retried. Schema — OPTIONAL error object code integer HTTP status code (same as the HTTP response status) message string Human-readable explanation of the error status string Possible values: [INVALID_ARGUMENT, UNAUTHENTICATED, FAILED_PRECONDITION, PERMISSION_DENIED, NOT_FOUND, UNIMPLEMENTED, RESOURCE_EXHAUSTED, INTERNAL, UNAVAILABLE] google.rpc.Code name for the error
401 Missing or invalid credentials (the X-User-Email and X-API-Key headers). Schema — OPTIONAL error object code integer HTTP status code (same as the HTTP response status) message string Human-readable explanation of the error status string Possible values: [INVALID_ARGUMENT, UNAUTHENTICATED, FAILED_PRECONDITION, PERMISSION_DENIED, NOT_FOUND, UNIMPLEMENTED, RESOURCE_EXHAUSTED, INTERNAL, UNAVAILABLE] google.rpc.Code name for the error
402 The account's credit balance does not cover this call. Do not retry until funds have been added. Schema — OPTIONAL error object code integer HTTP status code (same as the HTTP response status) message string Human-readable explanation of the error status string Possible values: [INVALID_ARGUMENT, UNAUTHENTICATED, FAILED_PRECONDITION, PERMISSION_DENIED, NOT_FOUND, UNIMPLEMENTED, RESOURCE_EXHAUSTED, INTERNAL, UNAVAILABLE] google.rpc.Code name for the error
413 The request body is over the 1 MB (1,048,576 byte) limit, or was sent with chunked transfer encoding. Requests must include a Content-Length header. Schema — OPTIONAL error object code integer HTTP status code (same as the HTTP response status) message string Human-readable explanation of the error status string Possible values: [INVALID_ARGUMENT, UNAUTHENTICATED, FAILED_PRECONDITION, PERMISSION_DENIED, NOT_FOUND, UNIMPLEMENTED, RESOURCE_EXHAUSTED, INTERNAL, UNAVAILABLE] google.rpc.Code name for the error
503 Scoring is temporarily unavailable. Retry after a few seconds (or the Retry-After interval, if the response gives one). Schema — OPTIONAL error object code integer HTTP status code (same as the HTTP response status) message string Human-readable explanation of the error status string Possible values: [INVALID_ARGUMENT, UNAUTHENTICATED, FAILED_PRECONDITION, PERMISSION_DENIED, NOT_FOUND, UNIMPLEMENTED, RESOURCE_EXHAUSTED, INTERNAL, UNAVAILABLE] google.rpc.Code name for the error