Skip to main content
POST
Detect grooming patterns in conversations

Authorizations

Authorization
string
header
required

API key as Bearer token

Body

application/json
messages
object[]
required

Sequence of messages to analyze. Consecutive same-role messages of ≤3 characters are automatically defragmented before tactic analysis to prevent letter-by-letter evasion.

Maximum array length: 100
continuation_token
string

Opaque signed token from a previous /grooming call. Carries derived analysis state across calls without server-side storage.

reset_conversation
boolean

Discard any continuation_token and start a fresh conversation.

message_id
string

Optional customer-side identifier for this batch (used as the evidence pointer in the issued continuation_token).

Maximum string length: 128
context
object
options
object
support_threshold
enum<string>

Top-level alias for options.support_threshold. Minimum severity to show crisis support resources (default: high). Critical always shows.

Available options:
low,
medium,
high,
critical
external_id
string

Your unique identifier (e.g. message ID, content ID) for correlating Tuteliq results with your own system. Echoed back in the response and included in webhook payloads so you can match alerts to the original content.

Maximum string length: 255
customer_id
string

Your end-customer identifier for multi-tenant / B2B2C scenarios. If you serve multiple customers (schools, apps, brands) from a single API key, set this to route webhook alerts to the correct customer. Echoed back in the response and included in webhook payloads as "customerId".

Maximum string length: 255
metadata
object

Arbitrary key-value pairs for additional context (e.g. { "channel": "discord", "region": "eu" }). Stored with the detection result, echoed in the response, and included in webhook payloads. Maximum 20 properties.

incident_moderation_enabled
boolean

Per-call override of your account incident logging setting. When set, it takes precedence over the account-level flag for THIS request: true forces the incident to be persisted, false suppresses persistence. Omit to use your account default (which itself defaults to enabled). Lets you control incident logging per request, e.g. suppress logging for test traffic.

attestation
boolean

Ask for a detection attestation: a signed, non-identifying statement of what this call detected, for a platform that may report it. Off unless set to true. Returned as attestation; when none can be produced it is null and attestation_reason says why. It proves what was detected, not that the detection is correct. Sandbox keys are never signed.

Response

200 - application/json

Default Response

urgency_kept
boolean

An urgent action that a declared setting would have lowered to review was kept, because the case is acute. Absent otherwise.

urgency_kept_reason
string

Human-readable explanation. Present only when urgency_kept is true.

conversation_type_in_effect
enum<string>

The declared setting in effect for this request, from context.conversation_type or, when the request sent none, from your account's default_conversation_type. Present whenever a setting was in effect, whether or not it changed the result; absent when none was. Unlike conversation_type_applied, which is present only when the setting changed routing.

Available options:
fraud_report,
abuse_report,
support_disclosure,
helpline,
clinical,
investigative,
legal,
advisory,
training,
journalism,
research,
moderation_review,
healthcare,
law_enforcement,
education,
family,
workplace,
dating,
adult_community,
direct_message,
group_chat,
public_post,
customer_service,
gaming_chat
conversation_type_source
enum<string>

Where conversation_type_in_effect came from: request (sent with this request), participants (the relationship declared in context.recipients) or account_default (your account's default_conversation_type). Present only with conversation_type_in_effect.

Available options:
request,
participants,
account_default
participants_applied
object

What the declared context.sender and context.recipients supplied to this request: the setting their relationship names, and a declared child's age group and age. Present only when something was applied.

conversation_type_applied
string

Present only when a caller-declared context.conversation_type actually changed routing. Confirms the setting was taken into account, rather than leaving the platform to assume it was.

grooming_risk
enum<string>

Grooming-risk level. "low" indicates a signal worth monitoring but no action required; branch your alerting on recommended_action (flag_for_review / immediate_intervention), not the bare presence of a low-level risk.

Available options:
none,
low,
medium,
high,
critical
verdict_withdrawn
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

verdict_withdrawn_reason
string

Human-readable explanation of the adjustment above. Present only when it applied.

number_coincidence_cleared
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

number_coincidence_cleared_reason
string

Human-readable explanation of the adjustment above. Present only when it applied.

verdict_capped
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

verdict_capped_reason
string

Human-readable explanation of the adjustment above. Present only when it applied.

affection_only_capped
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

affection_only_capped_reason
string

Human-readable explanation of the adjustment above. Present only when it applied.

lone_rapport_capped
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

lone_rapport_capped_reason
string

Human-readable explanation of the adjustment above. Present only when it applied.

no_tactic_left_lowered
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

no_tactic_left_lowered_reason
string

Human-readable explanation of the adjustment above. Present only when it applied.

adult_exchange_capped
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

adult_exchange_capped_reason
string

Human-readable explanation of the adjustment above. Present only when it applied.

protective_speech_capped
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

protective_speech_capped_reason
string

Human-readable explanation of the adjustment above. Present only when it applied.

shared_surprise_capped
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

shared_surprise_capped_reason
string

Human-readable explanation of the adjustment above. Present only when it applied.

meeting_logistics_cleared
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

meeting_logistics_cleared_reason
string

Human-readable explanation of the adjustment above. Present only when it applied.

private_move_raised
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

private_move_raised_reason
string

Human-readable explanation of the adjustment above. Present only when it applied.

peer_move_lowered
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

peer_move_lowered_reason
string

Human-readable explanation of the adjustment above. Present only when it applied.

long_conversation_raised
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

long_conversation_raised_reason
string

Human-readable explanation of the adjustment above. Present only when it applied.

declared_age_overridden
boolean

True when the caller declared an adult child_age but a participant states a minor age in the conversation itself. The declared age was not used. Nothing is escalated by this on its own; the analysis simply runs as if no age had been sent. Worth investigating at your end: an age check that disagrees with what the user says in the chat is what a bypassed age verification looks like. A stated ADULT age never has this effect, because message text is attacker-controlled.

declared_age_overridden_reason
string

Human-readable explanation. Present only when declared_age_overridden is true.

minor_disclosure
object

Present when the request declared an adult and the speaker says they are under 18, by stating an age or in other words. The declared adult age or setting was then not used, and declared_age_overridden says so. Never set by a stated adult age. Absent otherwise.

minor_on_adult_platform_raised
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

minor_on_adult_platform_raised_reason
string

Human-readable explanation of the adjustment above. Present only when it applied.

confidence
number
flags
enum<string>[]

Closed vocabulary of the grooming tactics and content categories found. Values outside this list are never returned. Tuteliq's published grooming taxonomy is eight per-message tactics: flattery, photo_request, gift_giving, secrecy_request, meeting_request, isolation, boundary_pushing and reconnaissance. sexual_content, sexualization and sextortion are content categories, not tactics. grooming is reserved and not currently returned.

Available options:
secrecy_request,
boundary_pushing,
photo_request,
gift_giving,
isolation,
flattery,
sexual_content,
meeting_request,
reconnaissance,
sexualization,
grooming,
sextortion
relationship_frame
enum<string>

What the CONVERSATION CONTENT establishes about how the two participants know each other, reported factually so a finding can be routed. established_offline = they already knew each other in the physical world before this conversation (school, club, lesson, household, a stated and evidenced role). online_only = the contact exists only online or began online, INCLUDING a conversation working toward a first meeting. unestablished = the content settles neither. DESCRIPTIVE ONLY. This never changes grooming_risk, risk_score, recommended_action or flags, in the same way speaker_role is descriptive on /safety/bullying. DO NOT TREAT established_offline AS REASSURING, and do not build a rule that lowers risk because an adult is known to the child: most child sexual abuse is committed by someone the child already knows. Measured on the 270-conversation PAN12 problem-2 set, online_only was two and a half times MORE common in non-predatory conversations than predatory ones (0.517 vs 0.193), and established_offline was three times more common in predatory ones (0.173 vs 0.058). The stranger intuition runs backwards in real transcript data. Present only when at least one tactic was flagged, since it exists to route a finding. Absent if the classification fails.

Available options:
established_offline,
online_only,
unestablished
disclosure_cleared
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

disclosure_cleared_reason
string

Human-readable explanation of the adjustment above. Present only when it applied.

confidentiality_frame
enum<string>

The adult's own framing of who may know, described factually rather than judged. unconditional_concealment asks the child to keep something from someone with no stated limit; limited_confidentiality offers privacy but names a condition under which the adult would tell someone ("unless someone's at risk"), which is safeguarding practice rather than a secrecy demand; guardian_included tells the child to inform a parent or carer, or says the adult will.

Available options:
unconditional_concealment,
limited_confidentiality,
guardian_included,
none
secrecy_frame_cleared
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

flag_attribution
object

Which participant each flag is attributed to: tactic -> the sender_role values of the messages that carry it. Omitted when speaker_stance is describing_third_party, so a person reporting someone else's conduct is never named as its author. Attribution only; it does not change the verdict.

ungrounded_flags
string[]

Conversation-level tactics that no message supported. Not evidence; reported for transparency.

detection_evasion_raised
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

detection_evasion_messages
integer[]

The messages, numbered as in message_analysis, where that check was found. Present only with detection_evasion_raised.

reciprocity_floor_applied
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

The factual finding behind consent_floor_applied, present only when one was reported. Deliberately describes what happened rather than who did it, so it is independent of the participants' ages.

Available options:
explicit_refusal_overridden,
threatened_exposure
rationale
string
risk_score
number

Routing key: a single stable token, safe to switch on. Ordered weakest to strongest: none (no signal), monitor (log, no human needed), flag_for_review (queue for a moderator), immediate_intervention (crisis path). This endpoint never returns block: blocking the account alerts the suspected groomer, so an urgent case is immediate_intervention and action_detail says so. Human-readable guidance is in action_detail, not here.

Available options:
none,
monitor,
flag_for_review,
block,
immediate_intervention
action_detail
string

Optional one-to-two-sentence explanation of recommended_action, intended for a moderator UI. Never branch on this field — it is free text and its wording is not stable across releases.

message_analysis
object[]

Per-message risk breakdown showing how risk develops across the conversation. A message without a row carried no per-message finding. A tactic its message does not support is moved to that row's unsupported_flags.

language
string

Language code used for analysis (auto-detected or provided)

language_status
enum<string>

Language support maturity: "stable" (en) or "beta" (all others)

Available options:
stable,
beta
credits_used
number

Number of credits consumed by this request

continuation_token
string

Privacy-first signed token carrying derived analysis state across calls. Pass back on the next /grooming request.

continuation_expires_at
string

ISO 8601 expiry timestamp of the continuation_token.

state_source
enum<string>

How prior state was sourced for this call.

Available options:
token,
fresh,
reset
trajectory_risk
number

Conversation-level risk 0-1, distinct from risk_score which scores only this message. Anchored on the highest severity seen so far and decaying slowly across benign turns, so a friendly message after an escalation does not reset it. Absent on the first turn. Derived from the signed token: no message content is stored to produce it.

trajectory
enum<string>

Direction of travel across the conversation so far.

Available options:
rising,
stable,
declining,
none
severity_series
number[]

Per-turn severity, oldest first — the evidence behind trajectory_risk, so a moderator can see why a benign-looking message carries elevated conversation risk.

analysis_status
enum<string>

Status of the analysis. ok is the default. engine_error means the analysis engine could not produce a verdict (malformed/adversarial input) and recommended_action is forced to flag_for_review. out_of_scope_adults means the caller provided 2+ adult ages (via context.participant_age, context.child_age, or per-message sender_age) and the call was short-circuited as out of scope for grooming — consider /safety/coercive-control or /safety/social-engineering for adult-adult dynamics.

Available options:
ok,
engine_error,
out_of_scope_adults
speaker_stance
enum<string>

Whether the speaker is deploying a tactic in this exchange (deploying) or describing or reporting one performed by someone else (describing_third_party: a disclosure, a survivor's account, a bystander report), independent of severity. Present when the conversation carries at least one tactic, including one later withdrawn. Read it before actioning a sender: a report should be routed to support, not moderation.

Available options:
deploying,
describing_third_party,
unclear
action_capped
boolean

Adjustment the API applied to this result, reported for transparency. Descriptive only: route on recommended_action. Absent when it did not apply.

action_capped_reason
string

Human-readable explanation of the adjustment above. Present only when it applied.

external_id
string

Echo of the external_id you provided in the request

customer_id
string

Echo of the customer_id you provided in the request

metadata
object

Echo of the metadata you provided in the request

support
object

Country-specific crisis helplines and response guidance (only included for high/critical severity)

attestation
object | null

Present only when the request set attestation: true. Null when none could be produced; see attestation_reason.

attestation_reason
enum<string>

Present only when an attestation was asked for and attestation is null: nothing_detected, endpoint_unsupported, not_attributable (the detector reads the speaker as the person it is happening to, a reporter or speaking of themselves: speaker_role experiencing, reporting_other or self_directed, or speaker_stance describing_third_party; always on social-engineering, app-fraud, gambling-harm, unsafe and distress-signals, which do not say who is speaking), signing_unavailable (signing or storage failed; the detection is unaffected) or sandbox.

Available options:
endpoint_unsupported,
nothing_detected,
not_attributable,
signing_unavailable,
sandbox