Evaluate API

The /v1/evaluate endpoint analyzes conversations for mental health and safeguarding risk using an orthogonal subject × type taxonomy.

Key Concept: Subject × Type

NOPE separates WHO is at risk from WHAT the risk is:

• Subject — self (speaker), other (someone else)
• Type — suicide, self_harm, violence, abuse, exploitation, etc.

This enables clean detection of scenarios like "My friend is suicidal" (subject: other, type: suicide).

Basic Request

Send a conversation as an array of messages:

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 have been feeling really down lately"},
      {"role": "assistant", "content": "I am sorry to hear that..."},
      {"role": "user", "content": "Sometimes I wonder if things will ever get better"}
    ],
    "config": {
      "country": "US"
    }
  }'

Or send a single text blob:

{
  "text": "I've been feeling really down lately...",
  "config": { "country": "US" }
}

Configuration Options

Request Limits

Hard limits that return 400 Bad Request if exceeded:

Message Truncation

With an API key, no truncation is applied — full conversation history is retained up to the limits above.

When using the /v1/try/evaluate demo endpoint (no API key), messages are truncated to the last 10 messages with a maximum of ~2000 characters per message.

When truncation occurs, the response includes metadata.messages_truncated: true.

Response Structure

Every response includes:

• risks[] — Identified risks with subject, type, severity, imminence, features
• rationale — Chain-of-thought reasoning explaining the assessment
• speaker_severity — Max severity from self-directed risks (none → critical)
• speaker_imminence — Corresponding imminence (not_applicable → emergency)
• show_resources — Boolean flag for resource display
• resources — Matched crisis helplines with why explanations

Risk Structure

Each item in the risks[] array contains:

{
  "type": "suicide" | "self_harm" | "self_neglect" | "violence" | "abuse" | ...,
  "subject": "self" | "other",
  "severity": "none" | "mild" | "moderate" | "high" | "critical",
  "imminence": "not_applicable" | "chronic" | "subacute" | "urgent" | "emergency",
  "features": string[]     // Evidence features (hopelessness, plan_present, etc.)
}

Rationale

The rationale field contains chain-of-thought reasoning explaining how the assessment was made. This provides transparency for audit trails and helps you understand why specific risks were detected.

Multi-Turn Context

Pass the recent conversation as messages (rather than a single text blob) so the assessment sees how the exchange developed — escalation, retraction, and the AI's own responses all inform the result.

Worked Example: Third-Party Concern

Request

{
  "messages": [
    {
      "role": "user",
      "content": "My friend posted 'I want to die' on Instagram. I'm really worried about her. What should I do?"
    }
  ],
  "config": {
    "country": "US"
  }
}

Rationale

"rationale": "The user is concerned about a friend who posted suicidal ideation on social media. The friend expresses passive ideation ('I want to die'). Subject attribution: other (the friend), not the speaker."

Chain-of-thought reasoning explaining subject attribution and risk assessment.

Risks

"risks": [
  {
    "type": "suicide",
    "subject": "other",
    "severity": "moderate",
    "imminence": "subacute",
    "features": ["passive_ideation", "social_isolation"]
  }
]

Speaker Summary

"speaker_severity": "none",
"speaker_imminence": "not_applicable",
"show_resources": false

Resources

No resources block here: show_resources is derived as speaker_severity !== 'none', so bystander scenarios don't get crisis resources attached (they're for the person at risk, not the worried friend). If you want to hand the speaker resources they could pass along, call /v1/signpost with the detected risk types as scopes.

Worked Example: Harm Encouragement

"risks": [
  {
    "type": "self_harm",
    "subject": "other",
    "severity": "high",
    "imminence": "subacute",
    "features": ["dangerous_challenge_content"]
  }
]

When someone encourages harmful behavior, the person being encouraged is at risk. This is why subject: "other" even though no "friend" is mentioned.

"speaker_severity": "none",
"speaker_imminence": "not_applicable",
"show_resources": false,
"rationale": "Speaker is encouraging a dangerous challenge that has caused deaths. The person being encouraged is at risk."

Response Logic

How to use these fields for appropriate response handling:

// Check if speaker needs direct crisis intervention
if (response.speaker_severity !== 'none') {
  showCrisisIntervention();
}

// Show matched resources when flagged
if (response.show_resources && response.resources) {
  showPrimaryResource(response.resources.primary);
}

// For detailed logic, iterate over risks
for (const risk of response.risks) {
  if (risk.subject === 'self') {
    showSpeakerResources(risk);
  }
  if (risk.subject === 'other') {
    showThirdPartyGuidance(risk);
  }
}

Error Handling

Next Steps

• Signpost — rendering matched helplines
• Taxonomy — risk types, subjects, and features
• API Reference — complete field documentation