API Reference — nefesh.ai Docs

Authentication

All requests require the X-Nefesh-Key header.

X-Nefesh-Key: YOUR_KEY

Endpoints

Method	Endpoint	Description
POST	/v1/ingest	Send signals, get state
GET	/v1/state?session_id=X	Read current state
GET	/v1/history?session_id=X&minutes=5	State history (1-60 min)
GET	/v1/triggers?subject_id=X	Trigger Memory profile

Trigger Memory

Send user_message + ai_response together with biometric signals to /v1/ingest. Nefesh auto-extracts psychological trigger topics and tracks how a user's stress changes around specific topics over time.

Important: subject_id must be set — it's the persistent user identifier across sessions. session_id only identifies the current session.

Example: Ingest with Conversation

curl -X POST https://api.nefesh.ai/v1/ingest \
  -H "X-Nefesh-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session-42",
    "subject_id": "user-abc-123",
    "heart_rate": 95,
    "tone": "anxious",
    "sentiment": -0.6,
    "user_message": "My manager just scheduled another performance review",
    "ai_response": "That sounds stressful. What specifically concerns you?",
    "timestamp": "2026-03-29T16:30:00Z"
  }'

Query Trigger Profile

curl "https://api.nefesh.ai/v1/triggers?subject_id=user-abc-123" \
  -H "X-Nefesh-Key: YOUR_KEY"

{
  "subject_id": "user-abc-123",
  "triggers": {
    "work_performance": {
      "status": "active",
      "avg_stress": 78,
      "peak_stress": 89,
      "sessions": 3,
      "last_seen": "2026-03-29T16:30:00Z"
    }
  },
  "active": ["work_performance"],
  "resolved": []
}

Rate Limits

Limit	Value
Per session	120 req/min
New sessions per key	50/min
Solo tier total	50,000 calls/month
Body size	4 KB max

Common Errors

Error	Cause	Fix
`422: sentiment — Input should be a valid number`	sentiment is a float, not a string	Use -1.0 to 1.0, NOT "negative"
`422: expression — Input should be 'relaxed', ...`	Invalid literal value	Only use allowed values (7 total)
`422: Extra inputs are not permitted`	Unknown field (e.g. hrv_sdnn)	Field is `sdnn` (no hrv_ prefix)
`401: Invalid API key`	Wrong or expired key	Check your API key
`429: Rate limit exceeded`	More than 120 req/min	Throttle requests
`413: Body too large`	Payload exceeds 4 KB	Reduce signal fields per request

Error Codes

Code	Meaning
400	Invalid payload, timestamp too old, missing signals
401	Missing or invalid X-Nefesh-Key
413	Body exceeds 4 KB limit
422	Validation error (wrong type or value)
429	Rate limit exceeded