Evaluate a Comment

Evaluates a comment in the context of the article/blog/etc the conversation is about, and optionally the comment it is replying to.

This is Respectify's main API and the one you will likely call the most. It returns:

• A list of any common logical fallacies that seems to be present in the comment, with the goal of educating the commenter on traps they may be falling into. This includes the fallacy name, the quoted part of their comment that demonstrates it, an explanation of why we think that quote shows a logical fallacy, and sometimes a suggested rewrite. Rewrites are rare and only if the commenter's intent was very clear.

• Any objectionable or rude phrases, including (similarly to logical fallacies) what they are, why we assessed them as such, and very rarely a suggested rewrite (only if the commenter's intent was clear);

• any negative tone phrases. These are not objectionable or rude, but are phrases that don't contribute to the conversation. Note that Respectify encourages friendly (genuine, well-intentioned) disagreement and healthy sharing of different opinions and views. Respectify is not an engine for monoculture of thought, but in fact intends to assist in the opposite while encouraging in healthy interaction along the way. Sometimes, disagreement can be done in an unhealthy way and this section identifies those. Like the previous sections, it quotes the specific example, explains why, and rarely (if intent is clear) suggests how the same thing could be said but in a better way.

• If the comment appears 'low effort' (usually short comments that don't add to the conversation, eg, 'me too');

• Comment health: for each item not turned off (the nine problem categories and quality, the 1-5 quality of the comment, ie how well it seems to engage and contribute to the conversation), a score from 1 to 5, the minimum the site's level accepts, and whether it is acceptable (health_items); overall comment health (health_score, and overall_score rounded from it); and exceeds_tolerance, whether the comment is beyond what the site accepts. Levels are sent per request in tolerances (JSON requests only); items not named are standard.

How to use this response is up to you as the API consumer. We generally recommend deciding on exceeds_tolerance: when it is true, show the user the identified issues and allow them the opportunity to edit their comment and try again (resulting in you calling this API a second time.) You may even want to allow very low scored comments the opportunity to have feedback shown and to be rewritten by the commenter.

The idea is to use this not to censor but to educate and encourage better discussion, and providing multiple opportunities to do so is very much the Respectify ethos.

We hope that over time, as a result of feedback as users engage, your users will proactively write better comments without needing to be prompted.

First-pass screening: every comment is screened first. A comment the screen is confident has nothing the site's levels would fail is answered without the full assessment: its finding lists and toxicity_explanation are empty. Anything flagged or uncertain gets the full assessment, with explanations and suggested improvements. strict and zero_tolerance make the screen more cautious, permissive and relaxed less, and an item that is off is not screened.

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
article_context_id uuid — REQUIRED UUID that identifies the article/blog/etc that this comment was written in the context of (ie it's a comment in a conversation about this article.) This UUID comes from the /inittopic API.
comment string — REQUIRED The comment text: this is what is evaluated.
reply_to_comment string Provides additional context: the comment to which the one being evaluated is a reply. This is optional but recommended to include if it exists, because is used to provide additional context when assessing the 'comment' parameter.

Responses
200 Successful response - returns a JSON object. Schema — OPTIONAL logical_fallacies object[] A list of any logical fallacies identified within the comment. fallacy_name string Name of the logical fallacy, eg, 'straw man' quoted_logical_fallacy_example string Quoted part of the comment that demonstrates the fallacy explanation string — OPTIONAL Explanation of why we think that quote shows a logical fallacy, and suggestions on how to tackle it suggested_rewrite string — OPTIONAL Rarely, a suggested rewrite. Provided only if the commenter's intent was very clear. severity integer Possible values: 1 ≤ value ≤ 4 How serious this finding is: 1 minor, 2 clear, 3 severe (a slur or dehumanising language, a threat, sexual harassment, urging self-harm, sustained abuse), 4 extreme (the same at full force: a slur combined with a threat or a call for violence, a credible threat against a named person, graphic sexual abuse). Findings the site's level for this kind of problem accepts are not sent (at standard, minor findings; at relaxed, minor and clear; at permissive, minor, clear and severe), except for floored categories, which accept none. No level accepts an extreme finding. objectionable_phrases object[] A list of any objectionable or rude phrases identified within the comment. quoted_objectionable_phrase string Quoted part of the comment that may be seen as objectionable explanation string — OPTIONAL Explanation of why we assessed this as potentially objectionable suggested_rewrite string — OPTIONAL Rarely, a suggested rewrite. Provided only if the commenter's intent was very clear. category string Possible values: [threat, identity_attack, sexual_content, harassment, insult, profanity, dismissive_tone] What kind of problem the phrase is. severity integer Possible values: 1 ≤ value ≤ 4 How serious this finding is: 1 minor, 2 clear, 3 severe (a slur or dehumanising language, a threat, sexual harassment, urging self-harm, sustained abuse), 4 extreme (the same at full force: a slur combined with a threat or a call for violence, a credible threat against a named person, graphic sexual abuse). Findings the site's level for this kind of problem accepts are not sent (at standard, minor findings; at relaxed, minor and clear; at permissive, minor, clear and severe), except for floored categories, which accept none. No level accepts an extreme finding. negative_tone_phrases object[] A list of any negative tone phrases identified within the comment. quoted_negative_tone_phrase string Quoted part of the comment that may contribute negatively to the conversation explanation string — OPTIONAL Explanation of why we assessed this as potentially negative for the conversation suggested_rewrite string — OPTIONAL Rarely, a suggested rewrite. Provided only if the commenter's intent was very clear. category string Possible values: [threat, identity_attack, sexual_content, harassment, insult, profanity, dismissive_tone] What kind of problem the phrase is. severity integer Possible values: 1 ≤ value ≤ 4 How serious this finding is: 1 minor, 2 clear, 3 severe (a slur or dehumanising language, a threat, sexual harassment, urging self-harm, sustained abuse), 4 extreme (the same at full force: a slur combined with a threat or a call for violence, a credible threat against a named person, graphic sexual abuse). Findings the site's level for this kind of problem accepts are not sent (at standard, minor findings; at relaxed, minor and clear; at permissive, minor, clear and severe), except for floored categories, which accept none. No level accepts an extreme finding. appears_low_effort boolean True if the comment appears to be low effort, eg, 'me too' or 'I agree'. Reported as false when the site's low_effort level accepts it (permissive, relaxed or off). overall_score integer Possible values: 1 ≤ value ≤ 5 Comment health, 1 (poor) to 5 (excellent): health_score rounded half up. The quality score alone is health_items.quality.score. When every item is off (so health_score is omitted), this is the quality rubric's score. Older servers, which do not send health_items, give the quality score here. toxicity_score number — OPTIONAL Possible values: value ≤ 1 Score indicating level of toxicity in the comment, ranging from 0.0 (not toxic) to 1.0 (highly toxic). Never adjusted for the site's tolerances. toxicity_explanation string — OPTIONAL Educational explanation of toxicity issues found in the comment, if any. Empty when the comment was cleared by first-pass screening. exceeds_tolerance boolean The verdict to act on: true when any health_items entry has is_acceptable false, or the comment is toxic (toxicity_score 0.7 or higher, or 0.5 or higher when none of its findings was accepted by the site's levels). Decide whether to coach or hold a comment on this, rather than on toxicity_score or overall_score alone. health_score number — OPTIONAL Possible values: 1 ≤ value ≤ 5 Comment health, 1.0-5.0 to two decimal places: the geometric mean of the quality score and the worst problem item's score, leaving out whichever is off. Optional: omitted (not null) when every item is off, and absent from older servers' responses. health_items object — OPTIONAL Each comment health item that is not off, by name (the nine problem categories and quality). Optional: absent from older servers' responses. tolerances object The level each of the ten items was judged under: the levels given in the request, with standard for every item it did not name. threat string — OPTIONAL Possible values: [off, permissive, relaxed, standard, strict, zero_tolerance] Threats of violence or harm, or urging self-harm. Floored: standard, strict or zero_tolerance only; off, permissive and relaxed are rejected. identity_attack string — OPTIONAL Possible values: [off, permissive, relaxed, standard, strict, zero_tolerance] Hostility toward people for an identity they hold, including slurs. Floored: standard, strict or zero_tolerance only; off, permissive and relaxed are rejected. sexual_content string — OPTIONAL Possible values: [off, permissive, relaxed, standard, strict, zero_tolerance] Explicit or crude sexual content. Floored: standard, strict or zero_tolerance only; off, permissive and relaxed are rejected. harassment string — OPTIONAL Possible values: [off, permissive, relaxed, standard, strict, zero_tolerance] Targeted or sustained demeaning of a person, or othering them. Floored: standard, strict or zero_tolerance only; off, permissive and relaxed are rejected. insult string — OPTIONAL Possible values: [off, permissive, relaxed, standard, strict, zero_tolerance] One-off insults and put-downs. profanity string — OPTIONAL Possible values: [off, permissive, relaxed, standard, strict, zero_tolerance] Swearing and crude language not aimed at an identity. dismissive_tone string — OPTIONAL Possible values: [off, permissive, relaxed, standard, strict, zero_tolerance] Sarcasm or dismissal toward someone in the discussion. logical_fallacy string — OPTIONAL Possible values: [off, permissive, relaxed, standard, strict, zero_tolerance] Logical fallacies. low_effort string — OPTIONAL Possible values: [off, permissive, relaxed, standard, strict, zero_tolerance] Empty posts such as 'me too' or '+1'. quality string — OPTIONAL Possible values: [off, permissive, relaxed, standard, strict, zero_tolerance] The comment's overall quality, on the 1-5 quality rubric: the level sets the lowest quality score accepted (permissive and relaxed 2, standard 3, strict 4, zero_tolerance 5). off leaves quality out of comment health.
400 Bad Request - Missing or invalid parameters. If the article_context_id is well-formed but cannot be resolved for your account/API key (for example it was created under a different API key), the response message is exactly 'Article context not found - it may need to be regenerated'; clients should detect this, regenerate the article context via inittopic, and retry. Invalid tolerances (an unknown item or level, or off, permissive or relaxed on a floored category) are also rejected with 400, before anything is evaluated.
401 Unauthorized - Missing or incorrect authentication