API Reference - Tuteliq

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

https://api.tuteliq.ai/api/v1

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

POST https://api.tuteliq.ai/api/v1/safety/bullying

Authentication

Include your API key in every request using one of these methods:

curl -X POST https://api.tuteliq.ai/api/v1/safety/bullying \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "message to analyze"}'

curl -X POST https://api.tuteliq.ai/api/v1/safety/bullying \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "message to analyze"}'

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.

{
  "is_bullying": true,
  "bullying_type": ["verbal_abuse", "exclusion"],
  "severity": "high",
  "risk_score": 0.85,
  "confidence": 0.92,
  "speaker_role": "enacting",
  "rationale": "Direct insults combined with social exclusion targeting a 10-12 year old.",
  "recommended_action": "flag_for_review",
  "action_detail": "Route to a moderator. The exclusion pattern suggests a group dynamic worth reviewing beyond this single message.",
  "language": "en",
  "language_status": "stable",
  "credits_used": 1
}

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

{
  "endpoint": "romance-scam",
  "detected": true,
  "level": "high",
  "severity": 0.78,
  "confidence": 0.92,
  "risk_score": 0.85,
  "categories": [
    { "tag": "URGENCY_FABRICATION", "label": "Fabricated Urgency", "confidence": 0.95 },
    { "tag": "FINANCIAL_REQUEST", "label": "Financial Request", "confidence": 0.88 }
  ],
  "evidence": [
    { "text": "I only need 4,000 to release it", "tactic": "FINANCIAL_REQUEST", "weight": 0.88 }
  ],
  "age_calibration": { "applied": true, "age_group": "10-12", "multiplier": 1.3 },
  "recommended_action": "flag_for_review",
  "rationale": "A financial request paired with fabricated urgency and an unverifiable absence.",
  "credits_used": 1
}

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.

Error response

Every error uses the same envelope, and request_id is the value to quote in a support ticket:

{
  "error": {
    "code": "AUTH_1001",
    "message": "API key is required. Include it as a Bearer token in the Authorization header or in the x-api-key header.",
    "request_id": "req_mu71meyo_ce663c02060d0914",
    "retryable": false,
    "status_url": "https://tuteliq.ai/status",
    "documentation_url": "https://docs.tuteliq.ai/error-handling#AUTH_1001"
  }
}

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:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded your rate limit of 300 requests per minute.",
    "suggestion": "Upgrade to Assure for 5,000 requests per minute.",
    "details": {
      "tier": "build",
      "limit": 300,
      "window": "1 minute",
      "retry_after_seconds": 42
    },
    "links": {
      "upgrade": "https://tuteliq.ai/dashboard/billing",
      "docs": "https://docs.tuteliq.ai/error-handling"
    }
  }
}

Context Fields

Pass a context object with any detection request to improve accuracy:

{
  "text": "message to analyze",
  "context": {
    "age_group": "13-15",
    "language": "en",
    "country": "GB",
    "platform": "Discord",
    "prior_messages": [
      { "role": "user", "text": "previous message" },
      { "role": "contact", "text": "response message" }
    ]
  }
}

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.

Field	Type	Description
`language`	string	ISO 639-1 code (e.g., `"en"`, `"de"`, `"sv"`). Auto-detected if omitted. 32 languages supported.
`platform`	string	Platform name (e.g., `"Discord"`, `"Roblox"`, `"WhatsApp"`). Adjusts for platform-specific norms.
`age_group`	string	`"under 10"`, `"10-12"`, `"13-15"`, `"16-17"`, or `"under 18"`. Triggers age-calibrated severity scoring. `ageGroup` is accepted as a camelCase alias.
`prior_messages`	array	Prior turns of the conversation, oldest first. Each needs `role` and `text`, with an optional ISO 8601 `timestamp`. Request-scoped: nothing here is retained after the call. `conversation_history` is accepted as a legacy alias.
`country`	string	ISO 3166-1 alpha-2 code (e.g., `"GB"`, `"US"`, `"SE"`). Enables geo-localised crisis helpline data. Falls back to the account’s country if omitted.
`conversation_type`	string	The setting the conversation was captured in. Honoured by `/safety/bullying`, `/safety/grooming`, `/safety/unsafe`, `/safety/distress-signals`, `/safety/radicalisation`, `/safety/tfgbv`, `/safety/gambling-harm`, `/safety/vulnerability-exploitation`, `/fraud/social-engineering`, `/fraud/romance-scam`, `/fraud/app-fraud` and `/fraud/mule-recruitment`. Not currently honoured by `/safety/coercive-control`, which applies its own cap for third-party reporters instead. Where the harm is discussed rather than enacted (`fraud_report`, `abuse_report`, `support_disclosure`, `helpline`, `clinical`, `investigative`, `legal`, `advisory`, `training`, `journalism`, `research`, `moderation_review`), urgent routing is capped at `flag_for_review`. Where the harm would be enacted in this exchange (`direct_message`, `group_chat`, `public_post`, `customer_service`, `gaming_chat`), nothing is capped. Severity, risk score, categories and evidence are never altered by this field, so the audit trail still shows what was actually found; `conversation_type_applied` comes back when the setting changed routing, so you can confirm it was honoured rather than assume. An unrecognised value behaves exactly like omitting the field. Set this from your own platform configuration, never from end-user input.
`sender_trust`	string	`"verified"`, `"trusted"`, or `"unknown"`. Verified senders suppress authority impersonation false positives.
`sender_name`	string	Sender identifier, used alongside `sender_trust` for impersonation scoring.
`relationship`	string	`/safety/bullying` only. Relationship between the participants, e.g. `"classmates"`.

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

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

Field	Type	Default	Description
`support_threshold`	string	`"high"`	Minimum severity to include crisis helplines. Values: `low`, `medium`, `high`, `critical`. Critical severity always includes support resources.
`verdict_only`	boolean	`false`	Fast mode. Skips generating `action_detail`, the moderator-facing expansion of `recommended_action`. The verdict itself (`severity`, `risk_score`, categories, `recommended_action`) and `rationale` are unchanged. See Fast mode.
`include_evidence`	boolean	`true`	Fraud and extended-harm endpoints. Include evidence excerpts with flagged phrases and weights.
`flag_profanity`	boolean	`false`	`/safety/bullying` and `/safety/unsafe`. Adds a deterministic word-list `profanity` block. Never affects the verdict, and costs no extra credits.
`flag_risk_terms`	boolean	`false`	`/safety/bullying` and `/safety/unsafe`. Adds a deterministic `risk_terms` block for bare drug and violence terms. Never affects the verdict.

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:

Plan	Requests/min	Detection credits/mo
Build ($99/mo)	1,000	25,000
Assure ($499/mo)	5,000	150,000
Enterprise	10,000	Custom
Sandbox	10	No credits consumed

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:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994
X-RateLimit-Reset: 1710000060

When exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Credits

Each endpoint consumes a different number of credits:

Endpoint	Credits	Notes
Text detection (bullying, grooming, unsafe, etc.)	1	Per call
Grooming / Emotions (with history)	1 per 10 messages	`ceil(messages / 10)`, minimum 1
Action plan	2	Longer generation
Incident report	3	Structured output
Synthetic content (text)	2	AI-generated text detection
Synthetic content (image)	5	Forensic vision + classification
Synthetic content (audio)	4	Transcription + classification
Synthetic content (video)	2 + 3/frame + 2 (audio)	Frame extraction + forensic vision + transcription
Image analysis	3	Vision + OCR + safety
Voice analysis	5	Transcription + safety
Age verification	5	Document/biometric
Document analysis	Dynamic	`max(3, pages × endpoints)` — details
Video analysis	10	Frame extraction + per-frame analysis
Identity verification	10	Document auth + face match + liveness

Every response includes credits_used and credit balance headers:

X-Credits-Remaining: 49,234
X-Monthly-Used: 766
X-Monthly-Limit: 50,000

Common Error Codes

Code	HTTP	Description
`AUTH_REQUIRED`	401	No API key provided
`AUTH_INVALID_KEY`	401	API key is invalid or unrecognized
`AUTH_EXPIRED_KEY`	401	API key has expired
`AUTH_INACTIVE_KEY`	401	API key is inactive
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded for your tier
`MESSAGE_LIMIT_REACHED`	429	Monthly credit limit reached
`TIER_ACCESS_DENIED`	403	Endpoint not available on your tier
`VAL_INVALID_INPUT`	400	Request body or parameters failed validation
`SVC_INTERNAL_ERROR`	500	Unexpected internal error (safe to retry)

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.

​Base URL

​Authentication

​Response Format

​Successful response

​Error response

​Context Fields

​Carrying conversation state

​Options

​Stateless by Design

​Sandbox Mode

​Rate Limits

​Credits

​Common Error Codes

​Endpoint Groups

Safety

Synthetic Content

Fraud Detection

Safety Extended

Document Analysis

Multi-Endpoint

Analysis

Guidance

Reports

Verification

Batch

Webhooks

Usage

Compliance

Health

Base URL

Authentication

Response Format

Successful response

Error response

Context Fields

Carrying conversation state

Options

Stateless by Design

Sandbox Mode

Rate Limits

Credits

Common Error Codes

Endpoint Groups