Endpoint
POST https://api.nefesh.ai/v1/ingest
Content-Type: application/json
X-Nefesh-Key: your-api-key
Required Fields
| Field | Type | Description |
|---|
| session_id | string | Client-generated UUIDv7 |
| timestamp | ISO 8601 | Max 24h old, max 5s future |
| (signal) | varies | At least one signal field required |
Signal Fields
Cardiovascular
| Field | Type | Range |
|---|
| heart_rate | number | 20–300 bpm |
| rmssd | number | 0–500 ms |
| sdnn | number | 0–500 ms |
| pnn50 | number | 0–100% |
| spo2 | number | 50–100% |
| mean_ibi | number | 200–2000 ms |
| ibi_count | integer | 1–120 |
Vocal
| Field | Type | Values |
|---|
| tone | string | hostile, anxious, frustrated, tense, hesitant, neutral, excited, focused, calm |
| speech_rate | number | wpm |
| pitch_variability | number | Hz std dev |
Visual
| Field | Type | Values |
|---|
| expression | string | tense, frowning, surprised, concentrated, neutral, smiling, relaxed |
| gaze | string | wandering, averted, downward, direct |
| posture | string | slouched, leaning_back, leaning_forward, upright |
| engagement | number | 0–1 |
Response: HumanStateResponse
{
"session_id": "string",
"state": "calm|relaxed|focused|stressed|acute_stress",
"stress_score": 0-100,
"confidence": 0.0-1.0,
"signals_received": ["cardiovascular", "vocal", ...],
"recommendation": "string",
"disclaimer": "Not a medical device."
}
Body Size Limit
Maximum 4 KB per request. Requests exceeding this limit receive HTTP 413.