The Happy Path Is the Easy Part

A successful POST /moderation call returns exactly two things: a categories object containing twelve boolean flags ( toxic , profanity , hate , harassment , self_harm , adult , violence , drugs , weapons , pii , spam , minor ) and a top-level flagged boolean that is true when any of those twelve is true. There is nothing else in the response — no scores, no probabilities, no confidence values, and no thresholds to tune. If you already have that call returning 200s, you got there somehow; our walkthrough on how to add text moderation in an afternoon is one route, and this article assumes you have finished it.

Production integrations rarely break on the response side. The response schema is small and fixed, so parsing it is not usually where your incident comes from. What breaks is the request side: a payload that violates the request schema, a key of the wrong type, an account that has run out of credits, and the occasional server-side failure.…