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.

Response

200 - application/json

Default Response

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 / block / immediate_intervention), not the bare presence of a low-level risk.

Available options:
none,
low,
medium,
high,
critical
confidence
number
flags
string[]
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), block (withhold or limit the content), immediate_intervention (crisis path). 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 escalates across the conversation

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
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
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)