Skip to main content
The Tuteliq API provides AI-powered child safety detection across text, voice, images, and video. This page covers everything you need to know before making your first call.

Base URL

All endpoints are prefixed with /api/v1. For example, the bullying detection endpoint is at:

Authentication

Include your API key in every request using one of these methods:
Get your API key from the Tuteliq Dashboard.

Response Format

Successful response

There are two response shapes, and which one you get depends on the endpoint family. Both carry confidence, 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.
severity means different things in the two families. In the core safety family it is an enum; in the fraud and extended-harm family it is a number from 0 to 1, and the enum is called level. Branch on recommended_action and you sidestep the difference entirely.
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.
Whichever family you are in, 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, and request_id is the value to quote in a support ticket:
Retryable errors add 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 a context 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_review because of a setting. ongoing_harm_floor_applied says 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_lowered or ongoing_harm_floor_applied, each with its reason where it has one.

Adult platforms

For an adult dating or social platform, declare dating. 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/grooming it is lowered with adult_exchange_capped; on /safety/unsafe an ordinary remark about adult life that shows no child is not sent for review (no_child_shown_capped).
  • With minor_disclosure_check turned on, a speaker who says they are under 18 raises a quiet result to flag_for_review.
What they do not change:
  • 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 child sender_role or a child_age under 18 removes the adult audience from the request, and so does a speaker stating an age under 18; declared_age_overridden tells 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. Set context.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_age of 18 or over, or a sender_age of 18 or over on every message;
  • or conversation_type dating, adult_community or workplace.
What it recognises. A speaker who states an age under 18, or says so in other words: a school year, a parent’s controls on their phone, a milestone such as being old enough to drive, or a description of their daily life that is only true of a child. Where it is supported. /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.
  1. The declared adult age and the adult-audience setting are not used for this request, and declared_age_overridden is true with a declared_age_overridden_reason.
  2. minor_disclosure describes the finding (fields below).
  3. On dating or adult_community, a result that asked for none or monitor is raised to flag_for_review, with the level at medium and the score in the review band, and minor_on_adult_platform_raised is true with 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.
  4. 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.
How this relates to 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.
Tuteliq does not keep 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. Pass context.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.
What this means for developers:
  • Pass context (age_group, platform, language, conversation_history) with every request that needs it.
  • Use external_id and customer_id to 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, and level fields 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 with environment: "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
Sandbox mode is for integration testing only. Daily limits prevent use as a free production workaround.

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.
Every response includes rate limit headers:
When exceeded, the API returns 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.