← Back to Docs

Quickstart Guide

1. Get Your API Key

Free (recommended to start)

  1. Go to nefesh.ai/signup
  2. Enter your email
  3. Get your API key instantly
  4. 1,000 API calls/month, all signal types, no credit card

Solo ($25/month)

For production: 50,000 calls/month, 120 req/min, email support. Upgrade anytime at nefesh.ai/pricing.

2. Generate a Session ID

Create a UUIDv7 on your client side. This identifies the human-device session.

import { v7 as uuidv7 } from 'uuid';
const sessionId = uuidv7();

3. Send Your First Signal

Python

import requests, datetime

resp = requests.post("https://api.nefesh.ai/v1/ingest",
    headers={"X-Nefesh-Key": "YOUR_KEY"},
    json={
        "session_id": "your-session-id",
        "timestamp": datetime.datetime.utcnow().isoformat() + "Z",
        "heart_rate": 72,
        "rmssd": 45.2,
    })
print(resp.json())

JavaScript

const resp = await fetch("https://api.nefesh.ai/v1/ingest", {
  method: "POST",
  headers: {
    "X-Nefesh-Key": "YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    session_id: "your-session-id",
    timestamp: new Date().toISOString(),
    heart_rate: 72,
    rmssd: 45.2,
  }),
});
console.log(await resp.json());

4. Read the Response

{
  "session_id": "your-session-id",
  "state": "relaxed",
  "stress_score": 28,
  "confidence": 0.9,
  "signals_received": ["cardiovascular"],
  "suggested_action": "maintain_engagement",
  "action_reason": "heart rate signal",
  "recommendation": "Maintain complexity. 3-5 sentences.",
  "disclaimer": "Not a medical device."
}

The suggested_action tells your agent what to do. The action_reason explains why. The recommendation provides human-readable style guidance.

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
  }
}

Use it to build self-improving agents:

  • effective: true → Current approach works. Continue.
  • effective: false → Stress increased despite the action. Try a different strategy.

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