Authentication
All requests require the X-Nefesh-Key header.
X-Nefesh-Key: nk_your_api_key_here
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) |
| DELETE | /v1/subjects/{subject_id} | GDPR cascading delete |
Rate Limits
| Limit | Value |
|---|
| Per session | 120 req/min |
| New sessions per key | 50/min |
| Solo tier total | 50,000 calls |
| Body size | 4 KB max |
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 |
| 429 | Rate limit exceeded |