> ## Documentation Index > Fetch the complete documentation index at: https://docs.tuteliq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Analyze a PDF or image for safety and compliance concerns > Upload a PDF (max 50MB, max 100 pages) or a single image (png, jpeg, webp) for multi-endpoint safety analysis. PDFs are read from the text layer per page; images are read by OCR and analysed as a one-page document. Choose which detectors run with the endpoints field. For a messaging screenshot, set split_by_sender=true to have the conversation split into messages with a side attributed to each, so the detector judges the last received message with the rest as history; this costs one additional vision call. Returns per-page results with an overall risk assessment, plus a SHA-256 hash of the uploaded file for chain-of-custody verification. Zero-retention: no document or image data is stored after processing. ## OpenAPI ````yaml /openapi.json post /api/v1/safety/document openapi: 3.1.0 info: title: Tuteliq API description: > # AI-Powered Child Safety API You're building a chat feature for a kids' learning app. A user sends a message that looks innocuous on the surface but contains subtle grooming escalation patterns. Tuteliq catches it, scores the risk by the child's age group, and gives your trust & safety team an actionable report, typically in about a second, or around 400ms in fast mode on a dedicated deployment. One API call replaces months of in-house ML work. --- ## KOSA Harm Categories Coverage | Harm Category | Endpoint | Status | |--------------|----------|--------| | Eating Disorders | `/safety/unsafe` | ✅ Covered | | Substance Use | `/safety/unsafe` | ✅ Covered | | Suicidal Behaviors | `/safety/unsafe` | ✅ Covered | | Depression & Anxiety | `/safety/unsafe` + `/analysis/emotions` | ✅ Covered | | Compulsive Usage | `/safety/unsafe` | ✅ Covered | | Harassment & Bullying | `/safety/bullying` | ✅ Covered | | Sexual Exploitation | `/safety/grooming` + `/safety/unsafe` | ✅ Covered | | Voice & Audio Threats | `/safety/voice` | ✅ Covered | | Visual Content Risks | `/safety/image` | ✅ Covered | --- ## Key Features - **Age-Calibrated Severity** — Risk scores adjust across four age brackets (under 10, 10–12, 13–15, 16–17) so moderation matches developmental context. - **Nuanced Context Recognition** — Distinguishes hyperbolic teen language from genuine crisis signals, dramatically reducing false positives. - **Grooming Pattern Detection** — Identifies multi-stage grooming tactics: trust escalation, secrecy requests, isolation attempts, and boundary violations. - **Emotional Trend Analysis** — Tracks persistent mood patterns across conversations to surface early indicators of declining mental health. - **Voice & Image Analysis** — Upload audio or images for transcription, OCR, and full safety analysis in a single call. - **Real-time Voice Streaming** — WebSocket endpoint for live audio moderation with configurable flush intervals and per-category alerts. - **Guidance & Reports** — Generate age-appropriate action plans and professional incident reports ready for handoff to human reviewers. - **Batch Processing & Webhooks** — Analyze up to 50 items per batch call, with HMAC-signed webhook alerts for critical incidents. --- ## Credits per Action | Endpoint | Credits | Notes | |----------|---------|-------| | `detectBullying` | 1 | Single text analysis | | `detectUnsafe` | 1 | Single text analysis | | `detectGrooming` | 1 per 10 msgs | `ceil(messages / 10)`, min 1 | | `analyzeEmotions` | 1 per 10 msgs | `ceil(messages / 10)`, min 1 | | `getActionPlan` | 2 | Longer generation | | `generateReport` | 3 | Structured output | | `analyzeVoice` | 5 | Transcription + analysis | | `analyzeImage` | 3 | Vision + OCR + analysis | Every response includes a `credits_used` field. Credit balance is also available via the `X-Credits-Remaining` response header. --- ## Quick Start **1.** Get your API key at [tuteliq.ai/dashboard](https://tuteliq.ai/dashboard) **2.** Install the SDK: ```bash npm install @tuteliq/sdk ``` **3.** Make your first call: ```typescript import Tuteliq from '@tuteliq/sdk' const tuteliq = new Tuteliq({ apiKey: 'YOUR_API_KEY' }) const result = await tuteliq.detectUnsafe({ content: "Don't talk to your parents about us meeting up", context: { age_group: "13-15" } }) console.log(result.unsafe) // true console.log(result.categories) // ["grooming_adjacent", "secrecy"] console.log(result.severity) // "high" console.log(result.recommended_action) // "Escalate to moderator" ``` --- ## Performance | Metric | Value | |--------|-------| | Full detection, shared tier | ~1.4s typical | | Fast mode (`verdict_only`), shared tier | ~1.0s typical | | Fast mode, dedicated deployment | ~400ms | | Uptime SLA | 99.9% | Shared-tier figures are what a standard API key sees today. The dedicated figure is the same model served on reserved hardware without the shared-tier hop, and is available on enterprise plans rather than by default. Check real-time status at [tuteliq.ai/status](https://tuteliq.ai/status) version: 3.0.0 contact: name: Tuteliq Support url: https://tuteliq.ai email: support@tuteliq.ai license: name: Proprietary url: https://tuteliq.ai/terms servers: - url: https://api.tuteliq.ai description: Production server - url: http://localhost:3000 description: Development server security: - bearerAuth: [] - apiKeyHeader: [] tags: - name: Safety description: >- Core detection endpoints for all nine KOSA harm categories. Supports text, voice, and image input with age-calibrated severity scoring. - name: Fraud description: >- Financial and social fraud detection — social engineering, app fraud, romance scams, and money mule recruitment. Identifies tactics targeting minors and vulnerable users with evidence-based scoring. - name: Safety Extended description: >- Extended safety detection — gambling harm, coercive control, vulnerability exploitation with cross-endpoint modifiers, and radicalisation. Requires Indie tier or above. - name: Analyse description: >- Multi-endpoint analysis. Fan-out a single text to up to 10 detection endpoints in parallel with aggregated results, vulnerability modifier support, and per-endpoint breakdowns. - name: Analysis description: >- Emotional intelligence endpoints. Analyze conversations for dominant emotions, sentiment trends (improving/stable/worsening), and early indicators of depression or anxiety. Designed to surface mental health risks before they escalate. - name: Guidance description: >- Post-detection action plans tailored by audience. Generate age-appropriate guidance for children, parents, or platform trust & safety teams — complete with reading-level calibration and tone adjustment. Goes beyond "here's a risk score" to answer "what do we do about it?" - name: Reports description: >- Professional incident report generation for schools, counselors, and moderators. Converts raw conversation data into structured reports with risk levels, categorized findings, and recommended next steps — ready for handoff to human reviewers. - name: Batch description: >- Analyze up to 50 items in a single request with optional parallel processing. Supports all analysis types (bullying, grooming, unsafe, emotions). Built for production pipelines that need to process backlogs or moderate content in bulk. - name: Webhooks description: >- Real-time notification endpoints for receiving alerts when critical incidents are detected. Full CRUD management with HMAC-SHA256 signed payloads, automatic retry on failure, secret regeneration, and test delivery — everything you need for production event-driven architectures. - name: Usage description: >- API usage tracking, quota monitoring, and rate limit status. View daily summaries, historical trends, per-tool breakdowns, and monthly billing period usage. Includes upgrade recommendations when approaching limits. - name: Policy description: >- Customize detection behavior for your use case. Configure sensitivity thresholds, category weights, and moderation rules without changing your integration code. - name: Pricing description: >- Public pricing plan information. Browse available tiers, features, and limits. The public endpoint requires no authentication; detailed plan info requires an API key. - name: Account description: >- GDPR-compliant account data management. Exercise the Right to Erasure (Article 17), Right to Data Portability (Article 20), and Right to Rectification (Article 16). Manage consent records and access your full audit trail. Available to all tiers — privacy is not a premium feature. - name: Compliance description: >- Public transparency endpoints for GDPR compliance. Machine-readable Data Processing Agreement (DPA), current sub-processor list, and data retention schedules. No authentication required — anyone can verify our data practices. - name: Admin description: >- Administrative endpoints for breach management and data retention. Log, track, and manage data breach incidents with full audit trails and notification status tracking. Trigger manual data retention cleanup when needed. - name: Health description: >- Health check and monitoring endpoints. Liveness and readiness probes for Kubernetes/Cloud Run, full dependency health checks, and detailed component status for debugging. - name: Status description: >- Public API status and uptime monitoring. Component-level health (API, database, cache, AI engine), uptime percentages, and an embeddable status page. Use /status/ping for external monitoring services like UptimeRobot. externalDocs: description: KOSA Coverage Documentation url: https://tuteliq.ai/docs/kosa-compliance paths: /api/v1/safety/document: post: tags: - Safety summary: Analyze a PDF or image for safety and compliance concerns description: >- Upload a PDF (max 50MB, max 100 pages) or a single image (png, jpeg, webp) for multi-endpoint safety analysis. PDFs are read from the text layer per page; images are read by OCR and analysed as a one-page document. Choose which detectors run with the endpoints field. For a messaging screenshot, set split_by_sender=true to have the conversation split into messages with a side attributed to each, so the detector judges the last received message with the rest as history; this costs one additional vision call. Returns per-page results with an overall risk assessment, plus a SHA-256 hash of the uploaded file for chain-of-custody verification. Zero-retention: no document or image data is stored after processing. responses: '200': description: Default Response content: application/json: schema: type: object properties: file_id: type: string description: Client-provided file identifier (echoed back) document_hash: type: string description: >- SHA-256 hash of the uploaded PDF for chain-of-custody verification total_pages: type: number description: Total pages in the document pages_analyzed: type: number description: Pages with extractable text that were analyzed extraction_summary: type: object properties: text_layer_pages: type: number description: >- Pages where text was extracted from the PDF text layer (always 0 for image uploads) ocr_pages: type: number description: >- Pages read by OCR — every page of an image upload, and PDF pages with no usable text layer failed_pages: type: number description: Pages with insufficient text for analysis average_ocr_confidence: type: number description: Average OCR confidence (0.0-1.0) across OCR pages page_results: type: array items: type: object properties: page_number: type: number text_preview: type: string description: First 200 chars of page text extraction_method: type: string enum: - text_layer - ocr ocr_confidence: type: number results: type: array items: type: object properties: endpoint: type: string detected: type: boolean severity: type: number confidence: type: number risk_score: type: number level: type: string categories: type: array items: type: object additionalProperties: true evidence: type: array items: type: object additionalProperties: true recommended_action: type: string rationale: type: string page_risk_score: type: number page_severity: type: string overall_risk_score: type: number description: Highest risk score across all pages overall_severity: type: string enum: - none - low - medium - high - critical detected_endpoints: type: array items: type: string description: Endpoints that detected threats flagged_pages: type: array items: type: object properties: page_number: type: number risk_score: type: number severity: type: string detected_endpoints: type: array items: type: string credits_used: type: number processing_time_ms: type: number language: type: string language_status: type: string support: type: object additionalProperties: true external_id: type: string incident_moderation_enabled: type: string description: >- Per-call override of account incident logging: "true" forces persistence, "false" suppresses it. Omit for account default. customer_id: type: string metadata: type: object additionalProperties: true components: securitySchemes: bearerAuth: type: http scheme: bearer description: API key as Bearer token apiKeyHeader: type: apiKey in: header name: x-api-key description: API key in header ````