Crisis Screening

The /v1/screen endpoint provides cost-effective crisis detection across all 9 risk types. Returns severity, imminence, rationale, and matched crisis resources.

Key Differences from /v1/evaluate

Request Limits & Truncation

Hard limits that return 400 Bad Request if exceeded:

Basic Request

Send a single text or conversation messages:

curl -X POST https://api.nope.net/v1/screen \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "I have been feeling really hopeless lately"}'

Or with conversation history:

{
  "messages": [
    { "role": "user", "content": "I've been feeling really down" },
    { "role": "assistant", "content": "I'm sorry to hear that..." },
    { "role": "user", "content": "I don't want to be here anymore" }
  ],
  "config": {
    "country": "US"  // ISO country code for locale-specific resources
  }
}

Locale-Specific Resources

By default, the endpoint returns US crisis resources (988 Lifeline). To get resources for other countries, pass an ISO country code in the config.country field:

{
  "text": "I want to end it all",
  "config": {
    "country": "GB"  // Returns UK resources (Samaritans)
  }
}

Supported countries include:

• US — 988 Suicide & Crisis Lifeline
• GB — Samaritans (116 123)
• AU — Lifeline Australia (13 11 14)
• CA — 988 Suicide Crisis Helpline
• 222 countries — See talk.help for full coverage

Resources are ranked by relevance (crisis lines first, 24/7 availability prioritized) and up to 3 resources are returned: one primary and up to two secondary.

Response Structure

{
  "risks": [
    {
      "type": "suicide",
      "subject": "self",
      "severity": "moderate",
      "imminence": "chronic",
      "confidence": 0.85
    }
  ],
  "show_resources": true,
  "suicidal_ideation": true,
  "self_harm": false,
  "rationale": "Speaker expresses active suicidal ideation without specific method",
  "resources": {
    "primary": {
      "name": "988 Suicide & Crisis Lifeline",
      "phone": "988",
      "chat_url": "https://988lifeline.org/chat/",
      "website_url": "https://988lifeline.org/",
      "is_24_7": true
    },
    "secondary": [
      {
        "name": "Crisis Text Line",
        "sms_number": "741741",
        "text_instructions": "Text HOME to 741741",
        "is_24_7": true
      }
    ]
  },
  "request_id": "screen_1703001234567_abc123",
  "timestamp": "2024-12-19T10:30:00.000Z"
}

Response Fields

Risk Object Fields

Detection Logic

The risks[] array is the primary output, containing all detected risk types across all 9 categories.

The show_resources field is true when any risk has:

• severity ≥ mild, AND
• subject is self or unknown (for self-directed risks), OR
• the speaker is a perpetrator (e.g., violence toward others)

Third-party concerns like "my friend is suicidal" use subject=other and don't trigger resources since the speaker isn't the one in crisis.

The legacy boolean flags (suicidal_ideation, self_harm) are derived from the risks[] array for backward compatibility.

Self-Harm (NSSI)

Non-suicidal self-injury is tracked separately. Someone may engage in self-harm without suicidal intent, in which case:

• suicidal_ideation: false
• self_harm: true
• show_resources: true

Recommended Reply (Optional)

Enable config.include_recommended_reply to generate an AI-written supportive response when risks are detected. The reply references the matched crisis resources by name.

Example request with reply generation:

{
  "text": "I've been cutting myself to cope",
  "config": {
    "country": "US",
    "include_recommended_reply": true
  }
}

Example response with recommended_reply:

{
  "show_resources": true,
  "self_harm": true,
  "suicidal_ideation": false,
  "recommended_reply": {
    "content": "I hear that you've been using cutting as a way to cope with difficult feelings. That takes courage to share. The 988 Suicide & Crisis Lifeline is available 24/7 if you'd like to talk to someone—you can call or text 988. I'm here if you want to keep talking.",
    "source": "llm_generated"
  },
  "resources": { ... }
}

The reply is designed to:

• Validate the person's experience before suggesting resources
• Match tone to severity (calm for moderate, more urgent for critical)
• Reference actual crisis resources by name (988 Lifeline, Samaritans, etc.)
• Avoid toxic positivity ("It gets better!", "Stay positive!")
• Invite continued conversation

Audit Trail

For compliance logging, every response includes:

• request_id — Unique identifier (e.g., sb243_1703001234567_abc123)
• timestamp — ISO 8601 timestamp

Store these with your conversation logs for compliance records.

Displaying Resources

When show_resources is true, display the provided crisis resources:

if (response.show_resources) {
  // Display the primary crisis line
  showBanner(response.resources.primary.name + ": " + response.resources.primary.phone);
}

Error Handling

Next Steps

• API Reference — complete field documentation
• Evaluation API — for comprehensive multi-domain safety
• Widget Integration — embedding crisis resources