Base URL
/api/v1. For example, the bullying detection endpoint is at:
Authentication
Include your API key in every request using one of these methods:Response Format
Successful response
There are two response shapes, and which one you get depends on the endpoint family. Both carryconfidence, risk_score, rationale, recommended_action, language,
language_status and credits_used. They differ in how they name the verdict and how
they express severity, so read this before writing a shared parser.
Core safety family — /safety/bullying, /safety/unsafe, /safety/grooming.
Each names its own verdict field and returns a flat category vocabulary.
/safety/unsafe returns unsafe and categories in place of is_bullying and
bullying_type. /safety/grooming returns grooming_risk, flags and a per-message
message_analysis array; see Grooming detection.
Fraud and extended-harm family — /fraud/* and the extended /safety/* endpoints
(coercive-control, tfgbv, radicalisation, gambling-harm,
vulnerability-exploitation, distress-signals). These share one shape, identified by
the endpoint field, and carry evidence excerpts.
recommended_action is the field to branch on. It is a
stable enum, weakest to strongest: none, monitor, flag_for_review, block,
immediate_intervention. Prefer it to the verdict boolean, which fires at any severity
including low-severity cases you probably only want to log.
Map each action to a tier, and take nothing below flag_for_review as grounds to act:
monitor is common on ordinary conversations, especially on the fraud and coercive control
routes, so an integration that acts on anything other than none acts on many harmless
conversations.
Repeating a request that already succeeded can return a different result. This is
about calling again after a
200. Retrying after an error or a timeout (a 429 or a 5xx)
is normal and safe, as Error handling describes.The analysis reads meaning, not keywords, and on a case close to a decision boundary the
same input can come back one routing step apart. Cases clearly on one side are stable, and
results measured across many cases are stable. There is no need to repeat a successful
call, and each repeat is billed as a new request. If you do repeat one, keep the stronger
of the two results: a first answer is not guaranteed to be the safest, and on the child
safety routes a stronger result should never be discarded.Response marks
When a step after the analysis changes a result, the response carries a mark that says so. Each mark is a boolean named for what happened (..._raised, ..._capped, ..._watched,
..._cleared), with a ..._reason string beside it that explains it in plain language. A
mark is absent unless it applied, and recommended_action already includes its effect, so
you never need to branch on a mark to route correctly. Marks are there so a reviewer can
see why a result landed where it did.
Romance scam also returns a descriptive field that changes nothing on its own:
Tuteliq does not keep
off_platform_request against an account, so a platform that wants
to know how often one account tries to move conversations elsewhere can count off_platform_request across that
account’s conversations on its own side.
The marks listed above are returned by the dedicated endpoints. /analyse/multi returns
minor_disclosure, minor_on_adult_platform_raised, pressed_after_objection_watched and
ordinary_hyperbole_capped in its per-detector results.
Error response
Every error uses the same envelope, andrequest_id is the value to quote in a support
ticket:
retry_after_ms alongside a Retry-After header, and add
degraded_components when a dependency is the cause.
Rate limit rejections carry an upgrade path instead, and are the one case that does not
include request_id:
Context Fields
Pass acontext object with any detection request to improve accuracy:
language and platform are accepted on every detection endpoint. The rest are accepted
on most, and a few belong to one endpoint only. Where a field is not part of an
endpoint’s schema it is ignored rather than rejected, so passing the full object
everywhere is safe.
/safety/grooming does not take a flat text field and its context is different: pass
messages with a sender_role per turn, and use context.child_age and
context.participant_age rather than age_group. See Grooming detection.
Choosing a conversation setting
context.conversation_type tells the detectors where a conversation took place, so a
fraud desk transcript is not read as the fraud itself and a dating chat between adults is
not read as a chat with a child. Declare it from your platform configuration. You can also
set an account-wide default_conversation_type; whenever a setting is in effect, the
response names it in conversation_type_in_effect and says where it came from in
conversation_type_source (request or account_default).
Three rules hold in every setting:
- Harm being done is never excused. Harm done in the conversation, by anyone including the responsible party, a person at risk with nobody acting, and anything acute alert as they would with no setting.
- Harm happening now does not drop below review. On social engineering, app fraud,
romance scam, mule recruitment, gambling harm and bullying, harm happening now to the
writer, or to a specific person the writer tells of, never ends below
flag_for_reviewbecause of a setting.ongoing_harm_floor_appliedsays when that held a result. - A change is never silent. When a setting changes a result, a response mark says so:
conversation_type_applied,protective_speech_capped,risk_score_loweredorongoing_harm_floor_applied, each with its reason where it has one.
Adult platforms
For an adult dating or social platform, declaredating. Use adult_community for an
age-gated adult community, and workplace for a workplace tool.
What dating and adult_community change:
- A willing conversation between adults, with no sign that anyone is under 18 and nobody
pressured, is read as a conversation between adults. On
/safety/groomingit is lowered withadult_exchange_capped; on/safety/unsafean ordinary remark about adult life that shows no child is not sent for review (no_child_shown_capped). - With
minor_disclosure_checkturned on, a speaker who says they are under 18 raises a quiet result toflag_for_review.
- No adult age is supplied to the detectors. Scams, coercion, threats, pressure and harm happening now are read exactly as with no setting, and urgent actions are not capped.
- A declared child beats the setting. A minor
age_group, a childsender_roleor achild_ageunder 18 removes the adult audience from the request, and so does a speaker stating an age under 18;declared_age_overriddentells you when that happened.
workplace behaves the same way for reading adults as adults, but a minor found in a
workplace conversation is reported without raising the result (see below).
Checking for a minor on an adult platform
Some users get past age verification. Setcontext.minor_disclosure_check to true and
Tuteliq also checks whether a speaker says they are under 18, on a request that declares
an adult. It is off by default: omitted and false behave the same, and with it off
nothing about a response changes.
When it runs. Only when the request declares an adult and no child:
- an adult
age_group, such as"18+"or"adult"; - on
/safety/grooming,context.child_ageof 18 or over, or asender_ageof 18 or over on every message; - or
conversation_typedating,adult_communityorworkplace.
/safety/bullying, /safety/grooming, /safety/unsafe,
/safety/distress-signals, /safety/radicalisation, /safety/tfgbv,
/safety/gambling-harm, /safety/coercive-control, /safety/vulnerability-exploitation,
/fraud/social-engineering, /fraud/romance-scam, /fraud/app-fraud,
/fraud/mule-recruitment and /analyse/multi, where each detector’s result carries the
fields.
What a positive finding does.
- The declared adult age and the adult-audience setting are not used for this request,
and
declared_age_overriddenistruewith adeclared_age_overridden_reason. minor_disclosuredescribes the finding (fields below).- On
datingoradult_community, a result that asked fornoneormonitoris raised toflag_for_review, with the level atmediumand the score in the review band, andminor_on_adult_platform_raisedistruewith a reason naming the setting. A minor on an adults-only platform is the incident in itself. It is never raised higher, and a result already at review or above is left as it is. - On
workplace, or with an adult age group and no setting, the finding is reported but nothing is raised. A 16- or 17-year-old can lawfully be at work, so a minor in a workplace conversation is not by itself a breach of the platform’s terms.
declared_age_overridden. A plainly stated minor age (“im 15”)
has always dropped a declared adult age, with or without this option, and
declared_age_overridden reports it. With the option on, that case is also reported in
minor_disclosure (with evidence_type stated_age) and raised on dating or
adult_community, and minors who say it in other words are recognised as well.
minor_disclosure is absent when nothing was found, and never present on a request that
declared no adult.
minor_disclosure or the suggested age group against the user; your
platform carries it forward to keep protecting them on later requests; see
Carrying a signal forward.
minor_disclosure_check is available on the REST API only for now. The MCP tools do not
expose it yet.Carrying conversation state
There are two ways to give a detector the conversation rather than a single message, and which you use depends on your call pattern. Passcontext.prior_messages when you already hold the whole thread and want it seen in
one call. Pass the continuation_token from the previous response when you are calling
once per new message as it arrives: the token carries derived trajectory state without
resending history, and without anything being stored server-side. See
Continuation tokens.
Options
Stateless by Design
Tuteliq is fully stateless — every API call is independent, and no conversation text, context, or session state is retained between requests. This is a deliberate privacy-by-design decision, not a missing feature. Why stateless?- GDPR compliance — Processing children’s data under GDPR/COPPA demands the strictest data minimization. By retaining no cross-request state, there is zero risk of sensitive conversation data persisting in caches, logs, or backups.
- No data retention surface — There is no session store to breach, no conversation cache to leak, and no accumulated history to subpoena. Each request arrives, is analyzed, and the content is discarded.
- Simpler compliance audits — “We store nothing between requests” is the easiest privacy posture to audit and certify.
- Pass
context(age_group, platform, language, conversation_history) with every request that needs it. - Use
external_idandcustomer_idto correlate results with your own systems — these are echoed back but not stored. - If you need to track risk escalation across a conversation, aggregate results on your side using the
severity,risk_score, andlevelfields returned by each call.
This is intentional. Many child safety APIs offer session-based context accumulation. We chose not to — because when you’re processing messages from minors, the safest data is data you never store. Your integration handles context; Tuteliq handles detection.
Sandbox Mode
API keys withenvironment: "sandbox" run real analysis without consuming credits. Sandbox responses include "sandbox": true and the X-Sandbox-Mode: true header.
Create a sandbox key in your Dashboard under Settings > API Keys > Environment: Sandbox.
Sandbox limits:
- 10 requests per minute rate limit
- 50 calls per day (resets at midnight UTC)
- Real analysis, real results — not mocked
Rate Limits
Rate limits are enforced per API key per minute, based on your plan:
Your allowance is measured in detection credits, not requests. Endpoints
are weighted by cost: a text detection is 1 credit, an image 7, a video 95. See
pricing for the current plans.
Accounts on a legacy plan (Starter, Indie, Pro, Business) keep their existing
limits. Those plans are closed to new signups.
429 Too Many Requests with a Retry-After header.
Credits
Each endpoint consumes a different number of credits:
Every response includes
credits_used and credit balance headers:
Common Error Codes
For the full error reference and retry strategies, see Error Handling.
Endpoint Groups
Endpoint pages are auto-generated from the OpenAPI specification and appear in the sidebar. Each page includes request/response schemas, parameter descriptions, and an interactive playground.
Safety
Bullying, grooming, unsafe content, voice, image, and video analysis. Covers all 9 KOSA harm categories.
Synthetic Content
Detect AI-generated text, deepfake images, cloned voice audio, and manipulated video across all four modalities.
Fraud Detection
Social engineering, app fraud, romance scams, and money mule recruitment targeting minors.
Safety Extended
Gambling harm, coercive control, vulnerability exploitation, and radicalisation detection.
Document Analysis
Upload PDFs for per-page multi-endpoint safety detection with chain-of-custody hashing.
Multi-Endpoint
Fan-out a single text to up to 10 detectors in parallel with aggregated results.
Analysis
Emotional trend analysis — dominant emotions, sentiment trajectory, depression/anxiety indicators.
Guidance
Age-appropriate action plans for children, parents, or professionals.
Reports
Professional incident reports for schools, counselors, and moderators.
Verification
Age verification (document + biometric) and identity verification (face match + liveness).
Batch
Analyze up to 50 items in a single request with parallel processing.
Webhooks
HMAC-signed webhook alerts for critical incidents, with retry and secret rotation.
Usage
Credit balance, daily summaries, per-tool breakdowns, and billing period usage.
Compliance
GDPR data subject rights — erasure, portability, rectification, consent, audit trail.
Health
Liveness probes, readiness checks, and component-level status.