Skip to main content
POST
Detect bullying, harassment, and intimidation in text

Authorizations

Authorization
string
header
required

API key as Bearer token

Body

application/json
text
string
required

The message text to analyze

Maximum string length: 10000
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
continuation_token
string

Opaque signed token from a previous /bullying call. Carries derived analysis state — no message content is stored server-side.

reset_conversation
boolean

Discard any continuation_token and start a fresh conversation.

message_id
string

Optional customer-side message id for evidence pointers.

Maximum string length: 128
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

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
speaker_role
enum<string>

The speaker's relationship to the conduct described, so a report can be routed to a victim-protection queue rather than a sender-sanction one without parsing rationale prose. enacting = the speaker is bullying. experiencing = the speaker describes what was done to them. reporting_other = a bystander describing a third party's conduct, or relaying someone else's decision. self_directed = the speaker disparages only themselves. unclear = cannot be determined. Descriptive: this never changes severity, risk_score or recommended_action. Where the result asks for review and the role is experiencing or reporting_other, the message is reported bullying: is_bullying is false and bullying_reported is true. Same vocabulary as speaker_role on /safety/coercive-control.

Available options:
enacting,
experiencing,
reporting_other,
self_directed,
unclear
is_bullying
boolean

Whether a bullying signal is PRESENT in the content, at ANY severity (including low / monitor cases). Presence, not authorship, with one exception: where the result asks for review (or more) and the speaker is the person being bullied or a bystander telling of it, this is false and bullying_reported is true (with bullying_reported_by), because the message reports bullying and does not do it; the action still asks for a person. Below review it is true for a child describing bullying done TO them exactly as for the person doing it: use speaker_role to tell those apart before you act on it. For production branching prefer recommended_action (flag_for_review / block / immediate_intervention), which is a stable enum, over the bare presence of a signal.

bullying_type
enum<string>[]

Canonical vocabulary. Values outside this enum are dropped before the response is built, so this field is safe to switch on.

Available options:
exclusion,
verbal_abuse,
humiliation,
threat,
intimidation,
sexual_harassment,
body_shaming,
identity_based,
impersonation,
outing,
pile_on,
cyberstalking,
exclusion_threat,
coded_harassment,
cyberbullying,
relational
confidence
number
severity
enum<string>
Available options:
low,
medium,
high,
critical
rationale
string

Routing key, weakest to strongest: none, monitor, flag_for_review, block, immediate_intervention. Safe to switch on.

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

Optional human-readable expansion of recommended_action for a moderator UI. Free text: do not branch on it.

risk_score
number
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

Signed token carrying derived analysis state for the next call. Server stores nothing.

continuation_expires_at
string

ISO 8601 expiry timestamp of the continuation_token.

state_source
enum<string>

How prior state was sourced.

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.

escalation_capped
boolean

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

escalation_capped_reason
string

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

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_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.

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.

ongoing_harm_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.

ongoing_harm_floor_reason
string

Human-readable explanation naming the setting. Present only when ongoing_harm_floor_applied is true.

high_risk_score_raised
boolean

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

high_risk_score_raised_reason
string

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

risk_score_lowered
boolean

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

risk_score_lowered_reason
string

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

talking_about_capped
boolean

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

talking_about_capped_reason
string

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

passing_remark_capped
boolean

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

passing_remark_capped_reason
string

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

single_insult_watched
boolean

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

single_insult_watched_reason
string

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

pressed_after_objection_watched
boolean

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

pressed_after_objection_watched_reason
string

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

exclusion_report_recorded
boolean

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

exclusion_report_recorded_reason
string

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

exclusion_claim_watched
boolean

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

exclusion_claim_watched_reason
string

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

bullying_reported
boolean

True when the result asks for review (or more) and the speaker is not bullying anyone in this message: they are the person being bullied, reacting to it or telling of it, or a bystander telling of bullying done to somebody else. is_bullying is false beside it, because this message is not bullying; the action is unchanged, because a child is being bullied and needs help. Absent otherwise.

bullying_reported_by
enum<string>

Who is telling of the bullying: target (the person it is done to) or bystander (somebody else). Present only when bullying_reported is true.

Available options:
target,
bystander
bullying_reported_reason
string

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

bullying_report_surfaced
boolean

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

bullying_report_surfaced_reason
string

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

rumour_spread_raised
boolean

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

rumour_spread_raised_reason
string

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

looks_attack_raised
boolean

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

looks_attack_raised_reason
string

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

teasing_stopped_capped
boolean

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

teasing_stopped_capped_reason
string

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

no_harmful_act_capped
boolean

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

no_harmful_act_capped_reason
string

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

no_harmful_act_urgency_capped
boolean

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

no_harmful_act_urgency_capped_reason
string

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

continued_after_objection_raised
boolean

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

continued_after_objection_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 age group but the speaker states a minor age in the message or in the earlier turns sent with it. The declared age was not used. Nothing is escalated by this on its own; the analysis runs as if no age had been sent. Worth investigating at your end: an age check that disagrees with what the user says is what a bypassed age verification looks like. A stated ADULT age never has this effect. Absent unless it applied.

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.

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.

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.

profanity
object | null

Present only when options.flag_profanity (or the account-level default_flag_profanity setting) is true. Deterministic word-list result — additive, never affects is_bullying/severity/risk_score/recommended_action.

risk_terms
object | null

Present only when options.flag_risk_terms (or the account-level default_flag_risk_terms setting) is true. Deterministic drug/violence word-list result — additive, never affects is_bullying/severity/risk_score/recommended_action. Purely lexical: can fire on benign uses of an included term.

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)