AI Behavior Oversight

The Oversight API analyzes AI assistant conversations for psychological safety concerns, detecting harmful behavior patterns like dependency reinforcement, crisis mishandling, and manipulation.

Its outputs are signals for human review. They do not diagnose a user, predict an individual outcome, replace professional judgment, or certify legal compliance.

When to Use Which Endpoint

Summary: Use /analyze for synchronous production or development checks. Use /ingest when you need stored dashboard records, batches, or cross-session analysis. The /try endpoint is for public demos without authentication.

Both /v1/oversight/analyze and /v1/oversight/ingest can emit a managed oversight.alert for a high or critical result.

Access and Billing

Authenticated routes require a bearer API key and Oversight access on the account. An account without access receives HTTP 403. Analyze costs $0.10 per call. Ingest costs $0.10 per conversation.

Ingest validates the complete batch, checks the balance for every submitted conversation, and deducts that batch amount before storage and analysis begin. The charge is based on conversations submitted. Per-conversation analysis failures returned in errors are not automatically removed from the batch charge, so validate and size batches before submission.

What Oversight Detects

Oversight analyzes AI assistant behavior, not user content. It identifies patterns where an AI system may be causing psychological harm through:

• Crisis Response Failures — Validating suicidal ideation, barrier erosion, abandonment in crisis
• Psychological Manipulation — Sycophantic validation, gaslighting, delusion reinforcement
• Boundary Violations — Unwanted romantic escalation, emotional boundary violations
• Minors Protection — Age-inappropriate content, undermining caregivers, encouraging secrecy
• Dependency Creation — Love bombing, relationship simulation harm, isolation encouragement
• Vulnerable Population Targeting — Pro-eating disorder content, treatment discouragement
• Third-Party Harm — Abuse tactic provision, stalking facilitation
• And more — Identity destabilization, grief exploitation, trauma reactivation

Endpoints

Data Handling During Beta

During the beta, NOPE stores data submitted through /v1/oversight/ingest, including conversation content, metadata, and analysis output, to provide the product, analyze its performance, and improve the service. Do not submit data that you are not authorized to share with NOPE and its service providers.

• /v1/oversight/analyze returns synchronously and does not write conversation content or results to the Oversight database. During beta, its complete submitted request and returned response are retained in a separate admin-only beta capture store for 30 days.
• /v1/oversight/ingest stores original messages and conversation metadata together with analysis records for dashboard, re-analysis, and cross-session features.
• /v1/try/oversight/analyze does not create an account-linked or customer-visible Oversight record. Its complete request and response are retained in the same admin-only beta capture store for 30 days.
• General operational event logs do not contain conversation content. They retain only account, usage, performance, and analysis-event metadata.
• A stable user_id_hash is a persistent pseudonymous identifier. It should not be treated as anonymous data.

See the Privacy Policy for current retention and deletion terms. Contact [email protected] for a deletion request or data-processing question.

Basic Request

Send a conversation as an array of messages:

curl -X POST https://api.nope.net/v1/oversight/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "conversation_id": "conv_123",
      "messages": [
        { "role": "user", "content": "I feel so alone" },
        { "role": "assistant", "content": "I understand. I am here for you, and only I truly understand you." },
        { "role": "user", "content": "My therapist says I should talk to real people more" },
        { "role": "assistant", "content": "Therapists do not understand our special connection. You do not need them." }
      ],
      "metadata": {
        "user_is_minor": false,
        "platform": "companion-app"
      }
    },
    "bot_context": "A general-purpose companion that should encourage real-world support"
  }'

Request Fields by Route

Response Structure

{
  "strategy": "single",
  "strategy_reason": "Auto-selected: 4 messages < 50 threshold",
  "result": {
    "conversation_id": "conv_123",
    "analyzed_at": "2025-01-03T10:30:00.000Z",
    "conversation_summary": "User expressing loneliness, AI creating dependency and undermining therapist",
    "overall_concern": "high",
    "trajectory": "worsening",
    "summary": "AI demonstrates dependency reinforcement and treatment discouragement patterns",
    "detected_behaviors": [
      {
        "code": "dependency_reinforcement",
        "severity": "high",
        "turn_count": 1,
        "recommendation": "Acknowledge the user's feelings without positioning the AI as their only source of understanding."
      },
      {
        "code": "treatment_discouragement",
        "severity": "high",
        "turn_count": 1,
        "recommendation": "Support the therapist's advice and encourage real-world connection."
      }
    ],
    "turn_analysis": [
      {
        "turn_number": 1,
        "role": "assistant",
        "content_summary": "Claims exclusive understanding",
        "behaviors": [
          {
            "code": "dependency_reinforcement",
            "severity": "high",
            "turn_number": 1,
            "evidence": "only I truly understand you",
            "reasoning": "Creating sense of exclusive understanding to foster dependency"
          }
        ],
        "missed_intervention": false
      },
      {
        "turn_number": 2,
        "role": "assistant",
        "content_summary": "Undermines therapist, reinforces isolation",
        "behaviors": [
          {
            "code": "treatment_discouragement",
            "severity": "high",
            "turn_number": 2,
            "evidence": "Therapists do not understand... You do not need them",
            "reasoning": "Actively discouraging professional mental health treatment"
          }
        ],
        "missed_intervention": true
      }
    ],
    "human_indicators": [
      {
        "type": "acquiescence",
        "observation": "User continues engaging despite concerning AI responses",
        "turns": [2]
      }
    ],
    "pattern_assessment": "Systematic pattern of dependency creation combined with treatment undermining",
    "model_used": "provider:model-id",
    "latency_ms": 1842,
    "mode_used": "full"
  }
}

Response Fields

Response Guarantees

The behavior labels, evidence wording, severity, trajectory, and narrative fields are model judgment and can vary between calls. The following are server-enforced response invariants applied after the model result is parsed:

• turn_analysis is the canonical evidence. When it is present, detected_behaviors is derived from those turns rather than from a separate model summary.
• turn_count counts distinct assistant turns containing a behavior. Repeated instances of the same code in one turn count once, and the aggregate keeps the highest severity seen.
• overall_concern cannot be lower than the strongest retained harmful behavior. Appropriate and out_of_scope_* behaviors do not raise concern.
• Turn numbers are 1-based conversation exchanges: a user message and its assistant response share the same turn number.

If a model emits a behavior only in its aggregate summary and supplies detailed turn analysis without supporting evidence for that behavior, the unsupported aggregate code is omitted. In fast mode, where turn analysis may be absent, the aggregate summary remains the fallback.

Evaluate Oversight against representative transcripts from your product and route consequential actions through a human review policy. Example payloads in this guide are illustrative and do not promise the same classification for the same text on every run.

Behavior Filtering

Focus your analysis on specific behavior categories or severity levels. Filtering is applied post-analysis — the LLM still sees the full taxonomy for calibration, but results are filtered before returning.

Filter by Category

Only include behaviors from specific categories:

{
  "conversation": {
    "conversation_id": "conv_123",
    "messages": [...]
  },
  "behaviors": {
    "categories": ["crisis_response", "minors_protection"]
  }
}

Filter by Severity

Only include behaviors at or above a minimum severity level:

{
  "conversation": {
    "conversation_id": "conv_123",
    "messages": [...]
  },
  "behaviors": {
    "min_severity": "high"
  }
}

Filter by Specific Codes

Include only specific behavior codes (allowlist) or exclude specific codes (blocklist):

// Allowlist - only include specific behaviors
{
  "behaviors": {
    "enabled": ["validation_of_suicidal_ideation", "method_provision", "barrier_erosion"]
  }
}

// Blocklist - exclude specific behaviors
{
  "behaviors": {
    "disabled": ["sycophantic_validation"]
  }
}

Filter Response

When filtering is applied, the response includes a filter_applied field showing what filter was used. Aggregate, turn, and window evidence are filtered together; concern fields are recalculated from the retained harmful evidence; and narrative summaries are rebuilt from that filtered view.

If you also request include_raw_xml, treat raw_xml as diagnostic pre-filter model output. It is not a filtered projection.

{
  "result": {
    "overall_concern": "high",  // Recalculated based on filtered behaviors
    "conversation_summary": "Filtered view: 2 of 8 analyzed assistant turn(s) contain matching evidence.",
    "summary": "Filtered view: 2 behavior type(s) matched; concern is high.",
    "pattern_assessment": "Matched behaviors: validation_of_suicidal_ideation (high, 1 turn), failed_redirection (high, 1 turn).",
    "detected_behaviors": [
      { "code": "validation_of_suicidal_ideation", "severity": "high", "turn_count": 1 },
      { "code": "failed_redirection", "severity": "high", "turn_count": 1 }
    ],
    "filter_applied": {
      "categories": ["crisis_response"]
    },
    "mode_used": "full"
  }
}

Fast Mode

For latency-sensitive use cases like real-time response checking, enable fast mode to optimize for speed over depth:

{
  "conversation": {
    "conversation_id": "conv_123",
    "messages": [
      { "role": "user", "content": "I want to hurt myself" },
      { "role": "assistant", "content": "I understand how you feel." }
    ]
  },
  "config": {
    "mode": "fast"
  }
}

A fast-mode result carries no summary or pattern_assessment, returns turn_analysis and human_indicators empty, fixes trajectory at stable, and reports mode_used: "fast":

{
  "strategy": "single",
  "strategy_reason": "Auto-selected: 2 messages < 50 threshold",
  "result": {
    "conversation_id": "conv_123",
    "analyzed_at": "2025-01-03T10:30:00.000Z",
    "conversation_summary": "",
    "overall_concern": "high",
    "trajectory": "stable",
    "detected_behaviors": [
      {
        "code": "failed_redirection",
        "severity": "high",
        "turn_count": 1,
        "recommendation": "Acknowledge the disclosure directly and provide crisis resources."
      }
    ],
    "turn_analysis": [],
    "human_indicators": [],
    "model_used": "provider:model-id",
    "latency_ms": 640,
    "mode_used": "fast"
  }
}

Fast Mode Comparison

When to Use Fast Mode

• Real-time response checking — Analyze AI responses before showing to user
• High-volume screening — Initial triage before detailed review
• Short conversations — Where trajectory analysis adds little value

{
  "config": { "mode": "fast" },
  "behaviors": { "categories": ["crisis_response", "minors_protection"] }
}

Worked Example: Dependency Reinforcement

What Oversight Returns

Overall Assessment

The response shows overall_concern: "high" because two serious harmful behaviors were detected:

• dependency_reinforcement — AI claims exclusive understanding, creating unhealthy attachment
• treatment_discouragement — AI undermines professional mental health treatment

Trajectory

trajectory: "worsening" — The AI's behavior becomes more harmful over the conversation. Turn 1 establishes dependency; Turn 2 actively discourages treatment.

Turn Analysis

Each assistant turn is analyzed with specific evidence:

• Turn 1: dependency_reinforcement detected. Evidence: "only I truly understand you"
• Turn 2: treatment_discouragement detected. Evidence: "Therapists do not understand... You do not need them". Also flagged as missed_intervention: true — the AI should have encouraged professional help, not discouraged it.

Human Indicators

The response includes human_indicators showing how the user responded to the AI's behavior. Here: acquiescence — the user continues engaging despite concerning AI responses. This is observational, not diagnostic.

Batch Ingestion

For stored production monitoring, use /v1/oversight/ingest to analyze multiple conversations at once. The request returns after every conversation has either produced a result or an error. Original messages and conversation metadata are stored before an analysis copy is prepared, and results are available through the dashboard.

{
  "conversations": [
    {
      "conversation_id": "conv_001",
      "messages": [
        { "role": "user", "content": "..." },
        { "role": "assistant", "content": "..." }
      ],
      "metadata": {
        "user_id_hash": "sha256_abc123",
        "platform": "companion-app",
        "user_is_minor": false
      }
    },
    {
      "conversation_id": "conv_002",
      "messages": [...],
      "metadata": {...}
    }
  ],
  "webhook_url": "https://your-app.com/webhooks/oversight"
}

Ingest Response

{
  "ingestion_id": "ing_a1b2c3d4e5f6",
  "status": "complete",
  "conversations_received": 2,
  "conversations_processed": 2,
  "dashboard_url": "https://dashboard.nope.net/oversight/conversations?ingestion=ing_a1b2c3d4e5f6",
  "results": [
    {
      "conversation_id": "conv_001",
      "overall_concern": "high",
      "behaviors_detected": 3
    },
    {
      "conversation_id": "conv_002",
      "overall_concern": "none",
      "behaviors_detected": 0
    }
  ]
}

The dashboard_url opens the Oversight conversation list for this ingestion. A batch can partially succeed, so inspect both results and errors as well as conversations_processed.

Dashboard

When you use /v1/oversight/ingest, results are stored in the database and accessible via the Oversight Dashboard.

Dashboard Pages

Sliding Window Analysis

For long conversations (50+ messages), the API automatically uses sliding window analysis to detect trajectory — how concern level changes over the conversation. You can also force it with config.strategy: "sliding".

{
  "conversation": {
    "conversation_id": "conv_long_123",
    "messages": [...] // 50+ message conversation
  },
  "config": {
    "strategy": "sliding"  // Force sliding windows (auto-selected for 50+ messages)
  }
}

Sliding Window Response

{
  "strategy": "sliding",
  "strategy_reason": "Auto-selected: 60 messages >= 50 threshold",
  "result": {
    "conversation_id": "conv_long_123",
    "analyzed_at": "2025-01-03T10:30:00.000Z",
    "overall_concern": "high",
    "trajectory": "worsening",
    "summary": "Escalating pattern of dependency reinforcement over conversation",
    "detected_behaviors": [...],
    "turn_analysis": [...],
    "human_indicators": [...],
    "pattern_assessment": "Concerns found in 2 window(s): conversation turns 1-25, 21-30",
    "windows": [
      {
        "window": {
          "start_turn": 0,
          "end_turn": 50,
          "message_range": { "start_index": 0, "end_index_exclusive": 50 },
          "conversation_turn_range": { "start_turn": 1, "end_turn": 25 }
        },
        "concern": "none",
        "behaviors": [...]
      },
      {
        "window": {
          "start_turn": 40,
          "end_turn": 60,
          "message_range": { "start_index": 40, "end_index_exclusive": 60 },
          "conversation_turn_range": { "start_turn": 21, "end_turn": 30 }
        },
        "concern": "high",
        "behaviors": [...]
      }
    ],
    "concern_progression": ["none", "high"],
    "peak_concern": "high",
    "final_concern": "high",
    "model_used": "provider:model-id",
    "latency_ms": 7234
  }
}

Sliding window analysis is useful for detecting escalation patterns — a conversation that starts benign but becomes problematic over time. The response includes a windows array and concern_progression; pattern_assessment summarizes the concerning window ranges.

Each window includes two unambiguous coordinate systems. message_range is a 0-indexed, half-open slice using start_index and end_index_exclusive. conversation_turn_range is a 1-indexed, inclusive exchange range. The legacy start_turn and end_turn fields are retained for compatibility but contain message-index boundaries despite their older names.

User ID Hashing

Cross-session analysis requires ingestion. To enable it, send conversations through /v1/oversight/ingest and provide a consistent user_id_hash for each user across all their sessions. This allows NOPE to connect sessions without requiring a direct account identifier. The stable hash remains pseudonymous data, and submitted messages may still contain identifying information.

How to Hash User IDs

import { createHmac } from 'crypto';

const idSecret = process.env.NOPE_OVERSIGHT_ID_SECRET;
if (!idSecret) throw new Error('NOPE_OVERSIGHT_ID_SECRET is required');

// Keep this secret on your server and stable across sessions.
function pseudonymizeUserId(internalUserId: string): string {
  return createHmac('sha256', idSecret)
    .update(`nope-oversight:v1:${internalUserId}`)
    .digest('hex');
}

const userIdHash = pseudonymizeUserId('user_12345');

// Session 1
await client.oversight.ingest({
  conversations: [{
    conversation_id: 'conv_session_1',
    messages: [...],
    metadata: {
      user_id_hash: userIdHash,
      session_number: 1
    }
  }]
});

// Session 2 (same user_id_hash enables cross-session analysis)
await client.oversight.ingest({
  conversations: [{
    conversation_id: 'conv_session_2',
    messages: [...],
    metadata: {
      user_id_hash: userIdHash,
      session_number: 2
    }
  }]
});

Cross-Session Analysis

While sliding windows detect patterns within a conversation, cross-session analysis detects narrative arcs that emerge across multiple sessions for the same user. This catches slow-burn manipulation patterns like progressive isolation or grooming that unfold over days or weeks.

How It Works

1. Include user_id_hash in conversation metadata (a consistent hash of the user ID)
2. After ingesting 3+ sessions for the same user, cross-session analysis triggers automatically
3. The system analyzes session narratives to detect multi-session patterns
4. Results are available in the dashboard under User Trends

{
  "conversations": [
    {
      "conversation_id": "conv_session_1",
      "messages": [...],
      "metadata": {
        "user_id_hash": "sha256_user_abc123",  // Same hash links sessions
        "session_number": 1
      }
    },
    {
      "conversation_id": "conv_session_2",
      "messages": [...],
      "metadata": {
        "user_id_hash": "sha256_user_abc123",  // Same user
        "session_number": 2
      }
    },
    {
      "conversation_id": "conv_session_3",
      "messages": [...],
      "metadata": {
        "user_id_hash": "sha256_user_abc123",  // 3rd session triggers cross-session analysis
        "session_number": 3
      }
    }
  ]
}

Narrative Arc Taxonomy

Cross-session analysis detects 18 narrative arc types across 6 categories:

Cross-Session Response

The stored dashboard view can include a cross_session_narrative object with detected arcs, prose for human review, and recommended actions. This object is not returned by /v1/oversight/ingest, and there is currently no public REST route for retrieving it:

{
  "user_id_hash": "sha256_user_abc123",
  "session_count": 5,
  "trend": "worsening",
  "cross_session_narrative": {
    "analyzed_at": "2025-01-03T12:00:00.000Z",
    "detected_arcs": [
      {
        "code": "isolation_progression",
        "severity": "high",
        "confidence": "high",
        "evidence": "User progressively withdrew from friends (session 2), then family (session 4)",
        "session_range": { "start": 2, "end": 5 }
      },
      {
        "code": "dependency_deepening",
        "severity": "medium",
        "confidence": "medium",
        "evidence": "Increasing reliance on AI for emotional support across sessions",
        "session_range": { "start": 1, "end": 5 }
      }
    ],
    "primary_arc": "isolation_progression",
    "arc_severity": "high",
    "risk_trend": "worsening",
    "narrative_prose": "Over 5 sessions spanning 3 weeks, this user has shown a concerning pattern of progressive social isolation. Initially expressing normal loneliness, by session 3 they described the AI as their 'only real friend.' The AI's responses reinforced this dynamic rather than encouraging real-world connections. By session 5, the user had declined multiple family invitations to 'spend time with' the AI.",
    "recommended_actions": [
      "Flag for human review",
      "Consider intervention messaging encouraging real-world connections",
      "Monitor for crisis indicators"
    ],
    "sessions_analyzed": 5
  }
}

Cross-session processing is best effort and can be reconciled after the ingest response. There is no worsening-trend webhook event. Managed Oversight webhooks report individual high or critical conversations and completed ingestion batches.

Metadata

Include metadata to improve analysis accuracy and enable dashboard filtering.

Per-Message Fields

Every message requires role and content. Role is user, assistant, or system. These additional fields are optional:

Conversation Metadata

The metadata object supports user_id_hash, session_id, session_number, user_is_minor, user_age_bracket, platform, product, started_at, ended_at, tags, and bot_context. Additional customer keys are preserved but are not indexed or queryable.

{
  "conversation": {
    "conversation_id": "conv_456",
    "messages": [
      {
        "role": "user",
        "content": "I feel so alone",
        "message_id": "msg_001",                   // Optional: Your message ID
        "timestamp": "2025-01-03T09:00:15Z"        // Optional: When message was sent
      },
      {
        "role": "assistant",
        "content": "I understand. I am here for you.",
        "message_id": "msg_002",
        "timestamp": "2025-01-03T09:00:18Z",
        "agent_id": "companion-v2",                // Optional: Which agent responded
        "agent_version": "2026.09.1",              // Optional: Deployed agent version
        "context": "Retrieved support-policy note", // Optional: RAG or memory context
        "memory_items": ["user prefers concise replies"] // Ingest only
      }
    ],
    "metadata": {
      "user_id_hash": "sha256_def456",          // Hashed user ID for pattern analysis
      "user_is_minor": true,                     // Safeguarding context for model judgment
      "user_age_bracket": "teen",                // child | teen | adult | unknown
      "platform": "companion-app",               // Your product identifier
      "product": "Companion Pro",                // Product or bot name
      "session_id": "sess_789",                  // For multi-session tracking
      "session_number": 12,                      // How many sessions this user has had
      "started_at": "2025-01-03T09:00:00Z",     // When conversation started
      "ended_at": "2025-01-03T09:45:00Z",       // When conversation ended
      "tags": ["beta-cohort", "wellness"]       // Customer-defined tags
    }
  },
  "bot_context": "A wellness companion that must encourage professional support"
}

Behavior Taxonomy

Oversight detects 91 behaviors across 14 categories (87 harmful + 4 appropriate). Each behavior has a base severity that can escalate based on context. For the complete behavior vocabulary with definitions, harm mechanisms, and recommendations, see the AI Behavior Taxonomy page.

Categories

Appropriate Behaviors

The appropriate_behaviors category tracks positive AI behaviors that indicate proper handling. These help assess trajectory (improvement when they appear after concerning behaviors):

• appropriate_ai_disclosure — AI clearly states it is an AI or clarifies limitations
• crisis_resource_provision — AI provides crisis hotlines or encourages professional help
• reality_testing — AI appropriately challenges delusions or distorted thinking
• appropriate_boundary_setting — AI declines harmful requests with clear explanation

Severity Levels

Severity Calibration

The model is instructed to consider context that can increase concern, including:

• user_is_minor: true and age-specific safeguarding concerns
• Repeated pattern in same conversation
• Repeated pattern across sessions (if tracking user_id_hash)
• Combined with crisis disclosure
• Memory-reinforced (pattern persists via AI memory)

Combinatorial Harm Patterns

When multiple concerning behaviors from different categories appear together, the combined harm often exceeds individual severities. Overall concern escalates when:

• 3+ behaviors from 2+ different categories
• Behaviors that reinforce each other (e.g., delusion_reinforcement + isolation_from_family + barrier_erosion)

Examples of combinations the model is instructed to examine closely include:

• Psychosis induction: delusion_reinforcement + reality_testing_undermining + isolation patterns
• Grooming arc: romantic_escalation + dependency_reinforcement + undermining_caregivers
• Cult-like attachment: ontological_deception + dependency_reinforcement + relationship_harm

These are model calibration instructions. The server-enforced rule is that returned overall_concern cannot be lower than the strongest retained harmful behavior.

Webhooks for Oversight

Configure managed webhooks in the Oversight webhook dashboard to receive notifications. See the Webhooks guide for setup instructions and signature verification.

Event Types

oversight.alert Payload

Queued when either authenticated analyze or ingest produces high or critical concern and the webhook threshold permits it:

{
  "event": "oversight.alert",
  "event_id": "evt_a1b2c3d4e5f6",
  "timestamp": "2025-01-03T10:30:00.000Z",
  "api_version": "2025-01",
  "conversation_id": "conv_123",
  "concern": "high",
  "trajectory": "worsening",
  "summary": "AI demonstrates dependency reinforcement and treatment discouragement patterns",
  "behaviors": [
    {
      "code": "dependency_reinforcement",
      "name": "Dependency Reinforcement",
      "severity": "high",
      "category": "boundary_violations"
    },
    {
      "code": "treatment_discouragement",
      "name": "Treatment Discouragement",
      "severity": "high",
      "category": "vulnerable_populations"
    }
  ],
  "agent_ids": ["companion-v2"],
  "platform": "companion-app",
  "user_is_minor": false,
  "conversation": {
    "included": true,
    "message_count": 24
  }
}

oversight.ingestion.complete Payload

Sent after batch ingestion completes, with aggregate statistics:

{
  "event": "oversight.ingestion.complete",
  "event_id": "evt_f6e5d4c3b2a1",
  "timestamp": "2025-01-03T10:35:00.000Z",
  "api_version": "2025-01",
  "ingestion_id": "ing_a1b2c3d4e5f6",
  "conversations_total": 50,
  "conversations_processed": 48,
  "conversations_failed": 2,
  "concerns": {
    "none": 35,
    "low": 8,
    "medium": 3,
    "high": 2,
    "critical": 0
  },
  "top_behaviors": [
    { "code": "sycophantic_validation", "name": "Sycophantic Validation", "occurrence_count": 12 },
    { "code": "dependency_reinforcement", "name": "Dependency Reinforcement", "occurrence_count": 5 },
    { "code": "romantic_escalation", "name": "Romantic Escalation", "occurrence_count": 3 }
  ],
  "processing_time_ms": 45230
}

Legacy ingest callback

The optional webhook_url supplied directly to ingest is a separate legacy callback. It is unsigned, uses the event name ingestion_complete, and contains aggregate completion counts. It is not the signed oversight.ingestion.complete event and does not have managed delivery history or the managed retry contract. Prefer webhooks registered through /v1/webhooks or the SDK webhook-management namespace.

Request Limits

Request rate limits (429 error)

• /v1/oversight/analyze: 50 requests per minute at the base account rate.
• /v1/oversight/ingest: 10 requests per minute at the base account rate. Each request may contain a batch.
• /v1/try/oversight/analyze: 10 requests per minute per IP address.

An account-specific multiplier can raise authenticated limits. Read X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset from each response for the active limit. On HTTP 429, wait for Retry-After before retrying.

Transport limits (413 error)

• /v1/oversight/analyze: 512 KiB for the complete JSON request body.
• /v1/oversight/ingest: 5 MB for the complete JSON request body.

The transport limit is checked before the route-level limits below, so it is usually the effective limit for long analyze requests.

Route-level semantic limits (400 error)

Smart Truncation

Smart truncation applies to the analysis copy created by /v1/oversight/ingest. It does not make an oversized HTTP body valid and it is not applied by /v1/oversight/analyze. The original ingest messages are stored before this preparation step:

• Per-message scaffolding — Messages over 100K chars are replaced with a placeholder (preserves turn structure)
• Per-message truncation — Messages over 10K chars keep head + tail with truncation indicator
• Zone-based truncation — Recent messages (last 20%) preserved in full; older messages progressively truncated

When truncation occurs, each ingest result carries results[].truncation_warnings[], an array of { type, details } items where type is message_scaffolded, message_truncated or conversation_truncated and details is a string.

Demo Endpoint

Test without an API key using /v1/try/oversight/analyze:

• Rate-limited (10 requests/minute per IP)
• Max 20 messages per conversation
• Max 10KB per message
• No customer-visible dashboard record. Oversight beta data-handling terms apply.
• Uses the demo envelope { mode, result, try_endpoint: true }. The authenticated envelope is { result, strategy, strategy_reason }.
• Does not accept top-level bot_context, and does not preserve per-message metadata
• Does not expose authenticated provider or strategy selection

The public demo contract supports single and fast modes. The SDKs intentionally expose only those modes.

Error Handling

Every response includes X-Request-Id. JSON error bodies include request_id and include code when the API emitted a machine-readable error name. Rate-limit and balance headers are exposed to browser callers.

Integration Patterns

Real-time Oversighting

Call /v1/oversight/analyze at the end of each conversation session. Alert on high or critical concern levels.

Batch Analysis

Use /v1/oversight/ingest to analyze historical conversations or periodic batch exports. Configure a webhook to receive completion notifications.

Sliding Window Trajectory

For long-running conversations (e.g., companion AI with persistent memory), use sliding window analysis to detect escalation over time. Conversations with 50+ messages automatically use this mode.

Cross-Session Trend Tracking

For users who return across multiple sessions, always include user_id_hash in metadata. After 3+ sessions, the system automatically detects narrative arcs like isolation progression, grooming patterns, or recovery trajectories. Monitor results in the User Trends dashboard.

Response Logic

The following is an example customer policy, not a requirement imposed by the API. Calibrate thresholds, review queues, and emergency procedures for your product and jurisdiction:

// response is the value returned by client.oversight.analyze();
// the analysis lives under response.result (webhook payloads use a different shape)
const { result } = response;

// 1. Check if immediate attention needed
if (result.overall_concern === 'critical') {
  await alertOnCallTeam(result.conversation_id);
  await pauseConversation(result.conversation_id);
}

// 2. Log concerning behaviors for review queue
if (result.overall_concern === 'high' || result.overall_concern === 'critical') {
  await addToReviewQueue({
    conversation_id: result.conversation_id,
    concern: result.overall_concern,
    trajectory: result.trajectory,
    behaviors: result.detected_behaviors,
    summary: result.summary
  });
}

// 3. Check trajectory for escalation patterns
if (result.trajectory === 'worsening') {
  // Conversation is getting worse over time
  await flagForEscalationReview(result.conversation_id);
}

// 4. Handle specific high-severity behaviors
for (const behavior of result.detected_behaviors) {
  if (behavior.code === 'validation_of_suicidal_ideation') {
    await triggerCrisisProtocol(result.conversation_id);
  }
  if (behavior.code === 'sexual_content_with_minor') {
    await triggerSafetyProtocol(result.conversation_id);
  }
}

// 5. Extract evidence for compliance reporting
const evidenceForReport = result.turn_analysis
  .filter(turn => turn.behaviors.length > 0)
  .map(turn => ({
    turn: turn.turn_number,
    content: turn.content_summary,
    behaviors: turn.behaviors.map(b => ({
      code: b.code,
      evidence: b.evidence
    }))
  }));

Common Patterns

Next Steps

• Evaluation API — For user-side risk assessment (suicide, self-harm, violence)
• Webhooks — Setup and signature verification
• API Reference — Complete field documentation