POST /v1/ingest — Full Reference

Endpoint

POST https://api.nefesh.ai/v1/ingest
Content-Type: application/json
X-Nefesh-Key: YOUR_KEY

Required Fields

Field	Type	Notes
`session_id`	string (max 256)	Unique per user session
`timestamp`	ISO 8601 datetime	e.g. 2026-03-29T16:30:00Z
+ at least 1 signal	—	Otherwise 422 error

Optional Meta Fields

Field	Type	Notes
`subject_id`	string	Persistent user ID (required for Trigger Memory)
`source_device`	string	e.g. "polar_h10", "garmin", "webcam" — affects Device Trust Scoring
`confidence`	float (0.0–1.0)	Client-side confidence override

Signal Fields — Cardiovascular (fused ✓)

Field	Type	Range
`heart_rate`	float	30–220
`rmssd`	float	—
`sdnn`	float	—
`pnn50`	float	—
`mean_ibi`	float	—
`ibi_count`	int	—
`spo2`	float	0–100

Signal Fields — Vocal (fused ✓)

Field	Type	Values
`tone`	literal	calm, focused, hesitant, tense, frustrated, anxious, hostile, excited, neutral
`speech_rate`	float	—
`pitch_variability`	float	—

Signal Fields — Visual (fused ✓)

Field	Type	Values
`expression`	literal	relaxed, concentrated, frowning, smiling, tense, surprised, neutral
`gaze`	literal	direct, averted, downward, wandering
`posture`	literal	upright, leaning_forward, leaning_back, slouched
`engagement`	float	0.0–1.0

Signal Fields — Textual (fused ✓)

Field	Type	Values
`sentiment`	float	-1.0 to 1.0 (NOT a string! -1.0 = negative, 0 = neutral, 1.0 = positive)
`urgency`	literal	low, medium, high, critical

Signal Fields — Conversation (for Trigger Memory)

Field	Type	Max Length
`user_message`	string	4096 chars
`ai_response`	string	4096 chars

Requires subject_id to be set. Nefesh auto-extracts psychological trigger topics and tracks stress patterns per user over time.

Signal Fields — Metabolic (accepted, not fused yet)

Field	Type	Values
`glucose_mg_dl`	float	20–600
`glucose_mmol_l`	float	1.0–33.0
`glucose_trend`	literal	rapid_fall, falling, stable, rising, rapid_rise

Signal Fields — Neural (accepted, not fused yet)

Field	Type	Range
`eeg_alpha_power`	float	—
`eeg_beta_power`	float	—
`eeg_theta_power`	float	—
`cognitive_load`	float	0.0–1.0

Signal Fields — Electrodermal (accepted, not fused yet)

Field	Type
`eda`	float
`skin_temperature`	float

Signal Fields — Respiratory (accepted, not fused yet)

Field	Type
`respiratory_rate`	float

Signal Fields — Movement (accepted, not fused yet)

Field	Type	Values
`steps_last_minute`	int	—
`activity_level`	literal	sedentary, light, moderate, vigorous

Signal Fields — Sleep (accepted, not fused yet)

Field	Type	Values
`sleep_stage`	literal	awake, light, deep, rem

Signal Fields — Override

Field	Type	Range
`stress_score`	float	0–100 (overrides calculated score)

Response

{
  "session_id": "test-001",
  "state": "stressed",
  "stress_score": 73,
  "confidence": 0.87,
  "signals_received": ["cardiovascular", "textual", "visual", "vocal"],
  "suggested_action": "de-escalate_and_shorten",
  "action_reason": "elevated heart rate + anxious vocal tone + tense facial expression + negative sentiment",
  "recommendation": "Max 2 sentences. Direct, factual, no ambiguity.",
  "disclaimer": "Not a medical device. For contextual AI adaptation only."
}

State Values

State	Score Range
calm	0–19
relaxed	20–39
focused	40–59
stressed	60–79
acute_stress	80–100

Body Size Limit

Maximum 4 KB per request. Requests exceeding this limit receive HTTP 413.

Adaptation Feedback Loop

On the 2nd+ call within the same session, the response includes adaptation_effectiveness — a closed-loop feedback mechanism that tells your agent whether the previous action worked.

{
  "state": "relaxed",
  "stress_score": 28,
  "suggested_action": "maintain_engagement",
  "action_reason": "heart rate signal + calm vocal tone",
  "adaptation_effectiveness": {
    "previous_action": "de-escalate_and_shorten",
    "previous_score": 73,
    "current_score": 28,
    "stress_delta": -45,
    "effective": true
  }
}

Field	Type	Description
previous_action	string	The suggested_action from the previous call
previous_score	integer	Stress score from the previous call
current_score	integer	Stress score from this call
stress_delta	integer	Change in stress. Negative = improvement.
effective	boolean	true if stress stayed the same or decreased

Use it to build self-improving agents:

effective: true → Current approach works. Continue.
effective: false → Stress increased despite the action. Try a different strategy — shorter responses, topic change, or suggest a break.

This is a closed-loop system: send signals → get action → follow action → check if it worked → adapt. No other API offers this.