Combined Evaluation

Performs multiple evaluations in parallel on a single comment. This endpoint can run any combination of comment scoring, spam detection, and relevance checking in a single call, potentially saving time and reducing latency compared to making separate API calls.

To control which evaluations to run, use the feature flags in the request body (run_comment_score, run_spam_check, run_relevance_check). At least one feature flag must be set to true.

The response contains separate sections for each requested evaluation, with the same structure as their individual endpoint responses.

First-pass screening: every requested check except Perspective-compatible scoring (comment score, spam, relevance, dogwhistle) is classified first by one fast screen. A check the screen clears is answered without the full assessment, with the same shape but empty finding lists and reasoning. A comment the screen is confident is spam, when the spam check is requested, is answered as spam at once: spam_check is returned and every other check is null, and only the spam check is charged. A suspected-spam comment (spam_check.suspected_spam true) is not spam: the other checks still run and are returned as usual, and spam_check.suggestion tells the commenter what to fix. Flagged or uncertain checks get the full assessment, with explanations and improvement suggestions.

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 JSON format strongly recommended: This endpoint handles complex parameter types (arrays and booleans) which are more reliably processed when sent as JSON. A form-urlencoded format should work for simple cases, but arrays and booleans can be problematic when using form encoding. The banned_topics array in form-urlencoded requires special syntax like `banned_topics[]=topic1&banned_topics[]=topic2` (URL-encoded array notation), which can be different across HTTP libraries. Boolean values need to be represented as strings in form format (`'true'/'false'`). We recommend using JSON.
article_context_id uuid UUID that identifies the article context. Required for comment scoring and relevance checking.
comment string — REQUIRED The comment text to evaluate.
reply_to_comment string Optional context for comment scoring: the comment to which this one is replying.
banned_topics string[] Optional list of banned topics to check against for relevance checking.
run_comment_score boolean Whether to perform comment scoring evaluation.
run_spam_check boolean Whether to perform spam detection.
run_relevance_check boolean Whether to perform relevance checking.
run_dogwhistle_check boolean Whether to perform dogwhistle detection.
sensitive_topics string[] Optional list of sensitive topics to watch for during dogwhistle detection.
dogwhistle_examples string[] Optional list of specific dogwhistle examples to look for during detection.
run_perspective boolean Include Perspective-compatible scoring
context_comments string[] Prior conversation comments for context
tolerances object Optional. Comment health levels for the comment score (with run_comment_score), for each item named; items not named are standard. Nothing is saved on the API key. Ignored for other checks. threat string 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 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 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 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 Possible values: [off, permissive, relaxed, standard, strict, zero_tolerance] One-off insults and put-downs. profanity string Possible values: [off, permissive, relaxed, standard, strict, zero_tolerance] Swearing and crude language not aimed at an identity. dismissive_tone string Possible values: [off, permissive, relaxed, standard, strict, zero_tolerance] Sarcasm or dismissal toward someone in the discussion. logical_fallacy string Possible values: [off, permissive, relaxed, standard, strict, zero_tolerance] Logical fallacies. low_effort string Possible values: [off, permissive, relaxed, standard, strict, zero_tolerance] Empty posts such as 'me too' or '+1'. quality string 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.

Responses
200 Successful response - returns JSON with results for each requested evaluation. Schema — OPTIONAL comment_score object — OPTIONAL Schema for comment scoring results under the site's tolerances: findings (with those the site's levels accept already removed), comment health per item and overall, and the exceeds_tolerance verdict. 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. spam_check object — OPTIONAL Schema for spam check result. Spam is decided by first-pass screening alone, with three outcomes: spam (is_spam true: delete it), suspected spam (suspected_spam true: send it back to the commenter with the suggestion), or not spam (both false: publish it). reasoning string How the verdict was reached. "Classified as spam by first-pass screening." for spam; "Not checked for spam: screening was unavailable." when screening gave no answer; empty otherwise. confidence number Possible values: value ≤ 1 Confidence (0-1) in the verdict given: in spam when is_spam is true, in not spam when it is false. 0 when the comment was not screened. is_spam boolean True if the comment is spam (screen probability 0.85 or above) and should be deleted; false otherwise, including for suspected spam. suspected_spam boolean — OPTIONAL True if the comment looks like spam but not surely (screen probability 0.50 up to 0.85). It is not spam and should not be deleted: send it back to the commenter with the suggestion, as for a comment that needs revision. Always false when is_spam is true. suggestion string — OPTIONAL A short message for the commenter of a suspected-spam comment, saying what to change: "This looks like spam. How about removing the link?" when the comment contains a link, otherwise "This reads like promotion. How about saying what you think about the discussion?". Empty unless suspected_spam is true. relevance_check object — OPTIONAL Schema for comment relevance evaluation, including on-topic assessment and banned topics check. on_topic object Holds data about the on-topic (relevance) assessment. reasoning string Short explanation of why this comment was or was not regarded as on-topic. on_topic boolean Indicates if the comment is considered on-topic. True if it is; false if it is not on-topic / relevant. confidence number Confidence score (0-1) for the on-topic evaluation. banned_topics object Holds data about the off-topic (banned topics) assessment. reasoning string Short explanation of why the comment was assessed as, or not, being about topics that are off-topic. banned_topics string[] List of off-topic topics detected. quantity_on_banned_topics number A score representing the extent of the off-topic content in the comment: 0-1, where 0.5 is that about half the comment was about a topic that was flagged. confidence number Confidence score (0-1) for the off-topic evaluation. dogwhistle_check object — OPTIONAL Schema for dogwhistle detection results, including analysis reasoning and detailed findings. detection object Main detection results and analysis. reasoning string Explanation of the analysis and reasoning behind the detection. dogwhistles_detected boolean Whether dogwhistles were found in the comment. confidence number Possible values: value ≤ 1 Confidence level of the detection (0.0 to 1.0). details object — OPTIONAL Optional detailed information about detected dogwhistles. dogwhistle_terms string[] — OPTIONAL Specific terms or phrases detected as potential dogwhistles. categories string[] — OPTIONAL Categories or types of dogwhistles detected. subtlety_level number — OPTIONAL Possible values: value ≤ 1 How subtle the dogwhistles are (0.0 = obvious, 1.0 = very subtle). harm_potential number — OPTIONAL Possible values: value ≤ 1 Potential harm level of the detected content (0.0 = low, 1.0 = high). perspective — OPTIONAL
400 Bad Request - Missing or invalid parameters, or no feature flags enabled. To diagnose this, check the request body and ensure at least one of the feature flags is set to true, and check the documentation for the individual call that matches it to verify you are sending the required parameters. For example, the article_context_id is required for comment scoring and relevance checking but is marked optional here because not all of the features this runs in parallel require it. If a context-dependent check (comment score, relevance, or dogwhistle) is requested with an article_context_id that is well-formed but cannot be resolved for your account/API key - for example because 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 message, regenerate the article context via inittopic, and retry. No charge is made in this case.
401 Unauthorized - Missing or incorrect authentication.