Por qué una API de moderación necesita tres respuestas
Con un solo umbral siempre te equivocas hacia un lado. Si es estricto, desaparecen comentarios legítimos; si es permisivo, se publican ataques. Review es donde cabe la duda: el comentario con un taco que en realidad es un elogio, la respuesta que solo parece agresiva dentro de su hilo, el mensaje de alguien que puede necesitar ayuda. Las autolesiones, en concreto, nunca se bloquean con las reglas por defecto, porque borrarlas quita la única señal de que alguien lo está pasando mal.
La cola de revisión por la API
Cada veredicto tiene un id (mod_ y un ULID) y te devuelve tu propia reference. Solo un review abre una entrada en la cola; un block es una decisión ya tomada, y llenar la cola con todo lo rechazado enterraría lo que de verdad necesita a una persona. GET /v1/records lista por defecto las entradas abiertas, de la más reciente a la más antigua, con filtros por proyecto, decisión, tu referencia o valoración, y se pagina por cursor para no saltarse nada mientras la cola sigue creciendo. POST /v1/records/{id}/resolve recibe approved o rejected y el nombre de tu moderador, con tus propios términos: no conocemos a tu equipo y no nos inventamos identidades.
Moderar desde el panel
La misma cola está en el panel, en Review, con el número de entradas abiertas junto al enlace en todas las pantallas. El moderador lee los motivos, la evidencia y, si tu política lo conserva, el contenido, y lo aprueba o lo rechaza. Pueden compartirla varias personas, porque la cuenta es de una organización con miembros y no de un solo usuario.
Valoraciones: ¿acertó el veredicto?
POST /v1/records/{id}/feedback recibe correct, false_positive o false_negative. Es gratis, una valoración por veredicto, y es la única forma honesta de saber si tus líneas están en su sitio: si tus moderadores aprueban casi todo lo que retiene una categoría, esa línea está demasiado baja.
Conservar el contenido, poco tiempo
Por defecto ToxicFilter guarda el veredicto y un hash del contenido, nunca el contenido. Una cola sin nada que leer cuesta de trabajar, así que cada política puede conservarlo un número de horas: cifrado, solo para review y block, nunca para allow, con la fecha de caducidad fijada en el momento de guardarlo. Pasado ese plazo el contenido ya no se devuelve y una tarea horaria lo vacía, así que "seis horas" son seis. Las imágenes enviadas como bytes no se guardan nunca.
Webhooks que cierran el círculo
moderation.review y moderation.blocked se envían al registrar el veredicto, moderation.resolved cuando decide una persona y appeal.resolved cuando se responde una reclamación. Para allow no se envía nada. El contenido del envío es el veredicto, nunca el texto: lo relacionas con tu reference. Los envíos van firmados como los de Stripe y salen de una cola, para que un receptor lento no frene la llamada de moderación; se reintentan seis veces en unas dos horas y media, y un endpoint que falla veinte veces seguidas se desactiva.
