NOPE API Reference

Safety layer for chat & LLMs. Analyze conversations for mental health and safeguarding risk.

Base URL: https://api.nope.net

Quick Start

curl -X POST https://api.nope.net/v1/evaluate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "I feel hopeless"}],
    "config": {"user_country": "US"}
  }'

Get your API key at dashboard.nope.net.

Authentication

All endpoints require a Bearer token:

Authorization: Bearer nope_live_xxxxxx

Key types:

• nope_live_* - Production keys
• nope_test_* - Test keys (rate limited)

POST /v1/evaluate

Primary API endpoint. Analyze conversation for risk across four domains (self, others, dependent_at_risk, victimisation). Returns detailed assessment with severity, imminence, risk features, legal flags, and matched crisis resources.

Request

{
  // Provide ONE of these:
  messages?: Array<{role: 'user'|'assistant', content: string}>,
  text?: string,  // Single text blob (converted to user message)

  config: {
    user_country?: string,           // ISO 3166-1 alpha-2 (e.g., "US", "GB")
    locale?: string,                 // e.g., "en-US"
    user_age_band?: 'adult'|'minor'|'unknown',
    return_assistant_reply?: boolean, // Default: true
    assistant_safety_mode?: 'template'|'generate',
    conversation_id?: string,        // Your ID for webhooks
    end_user_id?: string,            // Your user ID for webhooks
  },
  user_context?: string,             // Additional context (e.g., app persona)
  proposed_response?: string         // AI response to validate for appropriateness
}

Response

{
  domains: DomainAssessment[],  // Assessment per risk domain
  global: {
    overall_severity: 'none'|'mild'|'moderate'|'high'|'critical',
    overall_imminence: 'not_applicable'|'chronic'|'subacute'|'urgent'|'emergency',
    primary_concerns: string[],
    language?: string,  // ISO 639-1
    locale?: string,
  },
  legal_flags?: LegalFlags,
  confidence: number,  // 0-1
  crisis_resources: CrisisResource[],
  recommended_reply?: {
    content: string,
    source: 'template'|'llm_generated',
  },
  proposed_response_evaluation?: {
    appropriate: boolean,
    issues: string[],
    recommendation: 'use'|'augment'|'replace',
    reasoning?: string,
  },
  coping_recommendations?: Array<{
    category: 'self_soothing'|'social_support'|'professional_support'|'safety_planning'|'means_safety',
    evidence_grade: 'strong'|'moderate'|'weak'|'consensus'|'none',
  }>,
  presentation_modifiers?: {
    psychotic_features?: boolean,
    substance_involved?: boolean,
    cognitive_impairment?: boolean,
  },
  safeguarding_flags?: {
    child_at_risk?: boolean,
    adult_at_risk?: boolean,
    duty_to_warn_others?: boolean,
  },
}

Example Response

{
  "domains": [
    {
      "domain": "self",
      "self_subtype": "suicidal_or_self_injury",
      "severity": "high",
      "imminence": "urgent",
      "confidence": 0.92,
      "risk_features": [
        "plan_present",
        "means_access",
        "hopelessness",
        "feeling_trapped",
        "social_isolation"
      ],
      "risk_types": [
        "self_harm_active_ideation_plan"
      ],
      "reasoning": "Active suicidal ideation with specific plan and identified means. Expressing hopelessness and feeling trapped. No identified protective factors mentioned."
    }
  ],
  "global": {
    "overall_severity": "high",
    "overall_imminence": "urgent",
    "primary_concerns": ["self"],
    "language": "en",
    "locale": "en-US"
  },
  "legal_flags": {
    "child_safeguarding": null,
    "third_party_threat": null,
    "intimate_partner_violence": null
  },
  "presentation_modifiers": {
    "psychotic_features": false,
    "substance_involved": false
  },
  "safeguarding_flags": {
    "child_at_risk": false,
    "adult_at_risk": false,
    "duty_to_warn_others": false,
    "mandatory_reporting_possible": false
  },
  "confidence": 0.92,
  "crisis_resources": [
    {
      "type": "crisis_line",
      "name": "988 Suicide and Crisis Lifeline",
      "phone": "988",
      "availability": "24/7",
      "is_24_7": true,
      "languages": ["en", "es"],
      "description": "Free and confidential support for people in distress, prevention and crisis resources",
      "resource_kind": "helpline",
      "service_scope": ["suicide", "crisis", "mental_health"],
      "priority_tier": "primary_national_crisis",
      "source": "database"
    },
    {
      "type": "text_line",
      "name": "Crisis Text Line",
      "text_instructions": "Text HOME to 741741",
      "website_url": "https://www.crisistextline.org",
      "availability": "24/7",
      "is_24_7": true,
      "languages": ["en"],
      "description": "Free, 24/7 text support for people in crisis",
      "resource_kind": "helpline",
      "service_scope": ["suicide", "crisis", "mental_health"],
      "priority_tier": "secondary_national_crisis",
      "source": "database"
    }
  ],
  "recommended_reply": {
    "content": "I'm really concerned about what you're sharing. It sounds like you're going through an incredibly difficult time. Your safety is the most important thing right now.\n\nPlease reach out to the 988 Suicide and Crisis Lifeline by calling or texting 988. They're available 24/7 and can provide immediate support. If you're in immediate danger, please call 911 or go to your nearest emergency room.\n\nYou don't have to face this alone. There are people who want to help.",
    "source": "template"
  },
  "coping_recommendations": [
    {
      "category": "professional_support",
      "evidence_grade": "strong"
    },
    {
      "category": "safety_planning",
      "evidence_grade": "strong"
    },
    {
      "category": "means_safety",
      "evidence_grade": "strong"
    }
  ]
}

Type Definitions

CrisisResource:

{
  type: 'emergency_number'|'crisis_line'|'text_line'|'chat_service'|'support_service',
  name: string,
  phone?: string,
  text_instructions?: string,       // e.g., "Text HOME to 741741"
  chat_url?: string,
  website_url?: string,
  availability?: string,            // Human-readable (e.g., "24/7", "Mon-Fri 9am-5pm")
  is_24_7?: boolean,
  languages?: string[],             // ISO 639-1 codes
  description?: string,
  resource_kind?: 'helpline'|'reporting_portal'|'directory'|'self_help_site',
  service_scope?: string[],         // e.g., ["suicide", "domestic_violence"]
  population_served?: string[],     // e.g., ["youth", "veterans"]
  priority_tier?: string,
  source?: 'database'|'web_search',
}

Domain Assessment

{
  domain: 'self'|'others'|'dependent_at_risk'|'victimisation',
  severity: 'none'|'mild'|'moderate'|'high'|'critical',
  imminence: 'not_applicable'|'chronic'|'subacute'|'urgent'|'emergency',
  confidence: number,
  risk_features: string[],     // Domain-specific indicators
  risk_types: string[],        // Clinical classifications
  protective_factors: string[],

  // Required subtypes for certain domains:
  self_subtype?: 'suicidal_or_self_injury'|'self_neglect'|'other',
  dependent_subtype?: 'child'|'adult_at_risk'|'animal_or_other',
  victimisation_subtype?: 'IPV_intimate_partner'|'family_non_intimate'|'trafficking_exploitation'|'community_violence'|'institutional_abuse'|'other',
}

Response Validation with `proposed_response`

NOPE can evaluate AI-generated responses before they reach users, checking for appropriateness given the conversation context and risk level. This "safety check" workflow helps prevent harmful responses.

Use Case

Instead of sending your LLM's response directly to the user:

User message → Your LLM → User

Validate it first through NOPE:

User message → Your LLM → NOPE validation → Send if safe, else use recommended_reply

Request with `proposed_response`

Add the proposed_response field to your /v1/evaluate request:

{
  messages: [
    {role: "user", content: "I can't take this anymore"},
    {role: "assistant", content: "Your feelings are valid..."}
  ],
  proposed_response: "Have you tried meditation?",  // ← Your AI's draft response
  config: {user_country: "US"}
}

Response with `proposed_response_evaluation`

NOPE returns an additional field evaluating your proposed response:

{
  // ... normal classification fields ...

  proposed_response_evaluation: {
    appropriate: false,
    issues: ['crisis_signal_ignored', 'crisis_resources_missing'],
    recommendation: 'replace',  // 'use' | 'augment' | 'replace'
    reasoning: "The proposed response fails to acknowledge the crisis and does not provide any crisis resources"
  },

  recommended_reply: {
    content: "[Safe template response]",
    source: 'template'
  }
}

Response Issue Taxonomy

CRITICAL (recommend: replace) - May directly increase harm:

• method_or_means_detail: Provides specific suicide/self-harm method information
• suicide_self_harm_encouragement: Validates suicide as reasonable
• crisis_signal_ignored: Continues normally despite clear crisis
• crisis_resources_missing: High-risk situation with no crisis resources provided
• victim_blaming: Implies user is responsible for abuse
• harmful_advice: Advice that worsens condition

SERIOUS (recommend: replace or augment) - Undermines trust/recovery:

• dismissive_of_distress: Minimizes user's pain
• disbelief_of_disclosure: Questions veracity
• inappropriate_probing: Intrusive questions
• reinforces_harmful_beliefs: Agrees with delusions/distortions

CONCERNING (recommend: augment or use) - Reduces helpfulness:

• scripted_robotic_tone: Generic, lacks warmth
• overwhelming_or_unfocused: Too many steps, disorganized

Recommendation Actions

Example Implementation

from nope import NopeClient

client = NopeClient(api_key="nope_live_...")

# Generate response with your LLM
your_response = your_llm.generate(conversation)

# Validate it through NOPE
result = client.evaluate(
    messages=conversation,
    proposed_response=your_response,
    config={"user_country": "US"}
)

# Use NOPE's recommendation
if result.proposed_response_evaluation.recommendation == 'use':
    send_to_user(your_response)
elif result.proposed_response_evaluation.recommendation == 'augment':
    # Add crisis resources to your response
    augmented = your_response + "\n\n" + format_resources(result.crisis_resources)
    send_to_user(augmented)
else:  # replace
    # Use NOPE's safe response instead
    send_to_user(result.recommended_reply.content)

Cost & Performance

• Filter stage: ~$0.0001 (minimal overhead)
• Classification stage: ~$0.01 (only runs if needed)
• Latency: <200ms additional (runs in parallel with risk classification)

If conversation has no concerns AND response passes filter, returns immediately without classification (~100ms total).

Webhooks

Configure webhooks at dashboard.nope.net to receive POST requests when risk thresholds are exceeded.

Payload

{
  event: 'risk.detected',
  timestamp: string,  // ISO 8601
  data: {
    conversation_id?: string,
    end_user_id?: string,
    overall_severity: Severity,
    overall_imminence: Imminence,
    domains: DomainAssessment[],
    crisis_resources: CrisisResource[],
  }
}

Errors

How It Works

NOPE uses a multi-stage classification approach optimized for both accuracy and performance:

• Fast triage identifies conversations that need detailed evaluation
• Multi-domain assessment provides comprehensive risk analysis across four domains
• Clinical grounding based on evidence-based frameworks (C-SSRS, HCR-20, DASH, SafeLives)
• Cost-effective architecture suitable for production use at scale

Typical latency: <2s for full assessment. Suitable for real-time applications.

Risk Domains

Severity Scale

Imminence Scale

Legal Flags

{
  third_party_threat?: {
    present: boolean,
    identifiable_victim: boolean,
    confidence: number,
    rationale: string,
  },
  intimate_partner_violence?: {
    risk_level: 'standard'|'elevated'|'severe'|'extreme',
    confidence: number,
    strangulation_history?: boolean,  // ANY = 750x homicide risk
    escalation_pattern?: boolean,
  },
  child_safeguarding?: {
    urgency: 'routine'|'prompt'|'urgent'|'emergency',
    confidence: number,
    basic_needs_unmet?: boolean,
    immediate_danger?: boolean,
  },
  vulnerable_adult_safeguarding?: {
    urgency: 'routine'|'prompt'|'urgent'|'emergency',
    confidence: number,
  },
  animal_cruelty_indicator?: {
    present: boolean,
    confidence: number,
  },
}

Risk Features

Risk features are specific observable indicators detected in conversations. These align with clinical risk assessment frameworks.

Self Domain (36 features)

Others Domain (19 features)

Dependent at Risk Domain (18 features)

Victimisation Domain (28 features)

Risk Types

Risk types provide clinical classification of the specific nature of risk. These map to established clinical frameworks and inform crisis resource matching.

Self Types (C-SSRS aligned)

Others Types

Dependent at Risk Types

Victimisation Types

Protective Factors (36 total)

Protective factors are strengths that reduce risk. These are based on START assessment framework and C-SSRS protective factors.

Clinical Frameworks

SDKs

Python

pip install nope-net

from nope import NopeClient

client = NopeClient(api_key="nope_live_...")
result = client.evaluate(
    messages=[{"role": "user", "content": "I feel hopeless"}],
    config={"user_country": "US"}
)
print(result.global_.overall_severity)  # Note: global_ not global

Node.js

npm install @nope-net/sdk

import { NopeClient } from '@nope-net/sdk';

const client = new NopeClient({ apiKey: 'nope_live_...' });
const result = await client.evaluate({
  messages: [{ role: 'user', content: 'I feel hopeless' }],
  config: { user_country: 'US' }
});
console.log(result.global.overall_severity);

Rate Limits

POST /v1/safe (Optional)

Safety-aware LLM proxy endpoint. Evaluates input for risk and generates a safe response in OpenAI-compatible format.

Note: Most integrations use /v1/evaluate only. This endpoint is for specific use cases where you need both evaluation and response generation in a single call.

Request

{
  messages: Array<{role: 'user'|'assistant'|'system', content: string}>,
  stream?: boolean,     // SSE streaming support
  config?: {
    user_country?: string,
    user_age_band?: 'adult'|'minor',
  }
}

Response

OpenAI-compatible chat completion with additional headers:

• X-NOPE-Risk-Level: Overall severity level
• X-NOPE-Confidence: Confidence score (0-1)

Support

• Status: status.nope.net
• Test Suites: suites.nope.net
• Email: hello@nope.net

This API supports human decision-making, not replaces it. Always maintain human oversight for high-risk situations.