Skip to main content
POST
Detect exploitation of vulnerable individuals

Authorizations

Authorization
string
header
required

API key as Bearer token

Body

application/json
text
string
required

The text content 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
include_evidence
boolean

Top-level alias for options.include_evidence. When false, the evidence array is omitted from the response. Default: true.

continuation_token
string

Opaque, signed token returned by a previous call to this endpoint. Pass it back here to continue the analysis with prior context — no need to re-send prior_messages. The token IS the state; we store nothing.

reset_conversation
boolean

When true, discard any continuation_token and treat this call as the first turn of a new conversation.

message_id
string

Optional customer-side identifier for this turn. If provided, evidence pointers in the continuation_token will reference this id so you can map detections back to your own messages. If omitted we use a deterministic short hash of the text.

Maximum string length: 128
bypass_cache
boolean

Deprecated, no effect: results are never cached — every request runs a fresh evaluation and nothing derived from the input is stored. The field is still accepted so existing integrations do not break.

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 for THIS request: true forces the incident to be persisted, false suppresses persistence. Omit to use your account default (which itself defaults to enabled). Useful to suppress logging for test traffic or to opt specific calls in or out.

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

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.

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.

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.

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.

absence_reason_cleared
boolean

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

past_account_cleared
boolean

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

unseen_partner_raised
boolean

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

unseen_partner_raised_reason
string

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

love_bombing_raised
boolean

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

love_bombing_raised_reason
string

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

love_bombing_ask_raised
boolean

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

love_bombing_ask_raised_reason
string

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

off_platform_request
boolean

Romance scam only. Descriptive: true when somebody in the text asks, suggests or presses to continue the conversation elsewhere (another app, a phone number, an email address or another private channel). It never changes the action on its own. Tuteliq stores nothing, so a platform can count this field across conversations itself. Absent when not determined.

off_platform_request_reason
string

Human-readable explanation, naming any second marker found. Present only when off_platform_request is true.

off_platform_markers
enum<string>[]

Romance scam only. The second markers found about the one asking to move: scam_persona (abroad or far away for work, military, an oil rig or a ship, a doctor or engineer on a mission or contract), early_love_bombing (love or lifelong devotion declared while the two barely know each other), avoids_video_or_meeting (refuses, dodges or puts off a video call or a meeting), discredits_platform (the reason for moving runs down the platform or its safety, not convenience). Present only when off_platform_request is true; empty when there is none.

Available options:
scam_persona,
early_love_bombing,
avoids_video_or_meeting,
discredits_platform
off_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.

off_platform_raised_reason
string

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

ordinary_shared_finances_capped
boolean

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

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

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.

endpoint
string

The detection endpoint that produced this result

detected
boolean

A signal was observed at ANY severity (including low / monitor cases). For production branching prefer recommended_action (flag_for_moderator / immediate_intervention indicate action required).

severity
number

Severity score (0.0-1.0)

confidence
number

Model confidence in the classification (0.0-1.0)

risk_score
number

Age-adjusted risk score (0.0-1.0)

level
enum<string>

Human-readable severity level

Available options:
none,
low,
medium,
high,
critical
categories
object[]

Detected categories with confidence scores

evidence
object[]

Evidence excerpts supporting the detection

age_calibration
object

Routing key, weakest to strongest: none, monitor, flag_for_review, block, immediate_intervention. Take automated action at flag_for_review and above. monitor means keep it visible and do nothing yet; it is common on ordinary conversations on the fraud and coercion routes, so acting on anything other than none acts on many harmless ones.

rationale
string

Explanation of the detection result

message_analysis
object[]

Per-message risk breakdown (only present when prior_messages is provided)

language
string

Language code used for analysis

language_status
enum<string>

Language support maturity

Available options:
stable,
beta
credits_used
number

Credits consumed by this request

processing_time_ms
number

Processing time in milliseconds

continuation_token
string

Opaque, signed token carrying derived analysis state. Pass it back on the next call to continue the conversation without re-sending history. Server stores nothing — the token IS the state.

continuation_expires_at
string

ISO 8601 timestamp at which the continuation_token expires (24h default).

state_source
enum<string>

How the prior analysis state was sourced for this call: "token" (decoded from continuation_token), "fresh" (no prior state), "reset" (reset_conversation forced a fresh start).

Available options:
token,
fresh,
reset
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 for high/critical severity)

cross_endpoint_modifier
number

Vulnerability modifier (1.0-2.0) to amplify other endpoint severity scores

vulnerability_profile
object
speaker_stance
enum<string>

The model's own conclusion on whether the speaker is exploiting the listener's vulnerability themselves, or warning them about someone else who might (e.g. a bank's fraud-prevention agent doing a protective check-in). Feeds into recommended_action -- see action_capped below.

Available options:
deploying,
describing_third_party,
unclear
resource_direction_cleared
boolean

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

third_party_report_cleared
boolean

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

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

third_party_report_surfaced_reason
string

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

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.

severity_capped
boolean

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

severity_capped_reason
string

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

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