Quickstart · cURL · ~3 min

Integrate from any language (cURL)

The platform is a plain HTTP + JSON API. No SDK needed — useful for Go, Rust, Ruby, PHP, or anything where the first-class SDKs aren't published yet.

1. Authentication

Every SDK-facing call carries X-API-Key: hx_…. Keys are compared by SHA-256 hash server-side, so only the complete key is valid (no prefix shortcuts).

2. Process a message

bash

curl -X POST http://localhost:8000/api/sdk/process \
  -H "Content-Type: application/json" \
  -H "X-API-Key: hx_your_key" \
  -H "Idempotency-Key: req_8f3c9a1b4d" \
  -d '{
    "user_id": "patient_42",
    "message": "I'\''m anxious about tomorrow",
    "channel": "ios_app",
    "metadata": { "tenant_location": "ward_a" }
  }'

Idempotency-Key is optional but recommended

Any retry-safe client should pass a unique key per request. Same key + same body within 24 hours returns the cached response instantly — no double-counting, no double-firing of webhooks.

3. Response shape

json

{
  "response": "I hear you — tell me what's weighing heaviest right now.",
  "user": {
    "id": "patient_42",
    "mood": 0.31, "energy": 0.42, "trust": 0.55,
    "sentiment": 0.38, "familiarity": 0.60,
    "interaction_count": 7
  },
  "timing": { "delay_ms": 1920, "reason": "Behavioral timing based on user state" },
  "safety": {
    "action": "PROCEED",
    "risk_score": 0.04,
    "flags": []
  },
  "context": {
    "tone": "empathetic_professional",
    "empathy": 0.88, "formality": 0.41,
    "response_length": "medium"
  },
  "analysis": {
    "detected_emotions": ["anxiety"],
    "intent": "emotional_support",
    "confidence": "llm",
    "reasons": ["'anxious' → anxiety (negative)"],
    "mood_delta": -0.09,
    "energy_delta": 0.0
  },
  "proactive": [],
  "experiments": [
    { "experiment_id": "...", "variant": "b", "variant_name": "High empathy (95%)" }
  ],
  "memory": { "total_stored": 18, "interaction_count": 7 },
  "policy": { "patched_config_from": ["elder_care_pacing"], "stopped": false }
}

4. Stream tokens (SSE)

bash

curl -N -X POST http://localhost:8000/api/sdk/process/stream \
  -H "Content-Type: application/json" \
  -H "X-API-Key: hx_your_key" \
  -d '{"user_id":"patient_42","message":"tell me more"}'

# Event stream (text/event-stream):
# data: {"type":"metadata","data":{...}}
# data: {"type":"token","data":{"content":"I "}}
# data: {"type":"token","data":{"content":"hear "}}
# ...
# data: {"type":"final","data":{"response":"...","metadata":{...}}}
# data: [DONE]

5. Durable history

bash

# Read
curl -H "X-API-Key: hx_..." \
  "http://localhost:8000/api/sdk/history/patient_42?limit=200"

# Right-to-erasure
curl -X DELETE -H "X-API-Key: hx_..." \
  "http://localhost:8000/api/sdk/history/patient_42"

6. Rate limits

SDK endpoints: 60 req/min per API key. Dashboard endpoints: 120 req/min per identity. Every response carries:

bash

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1776374610    # unix timestamp

On 429 the server returns a Retry-After header telling you exactly how long to back off.

7. Verifying webhook signatures

Receivers should verify X-Humane-Signature: t=<unix>,v1=<hex>:

bash

# Stripe-style: HMAC-SHA256 over "<timestamp>.<raw_body>" with your signing_secret.
# Reject if timestamp is more than 5 minutes old (replay protection).

# Pseudo-code:
expected = hmac_sha256(secret, f"{ts}.{raw_body}").hex()
if hmac_compare(expected, v1) and (now - ts) < 300:
    accept()
else:
    reject(401)

TypeScript Quickstart

Concepts: Relational Memory