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. The fastest call is /observe: state + risk in one POST, no onboarding required.

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. Observe a turn

Send a completed conversation turn — the user's message and (optionally) your AI's reply — and get back behavioral state, a risk level, and any safety alerts. No LLM runs; nothing is generated.

bash

curl -X POST https://humaneai.vaarak.com/api/sdk/observe \
  -H "Content-Type: application/json" \
  -H "X-API-Key: hx_your_key" \
  -d '{
    "user_id": "u_8f2",
    "user_message": "honestly I don'\''t know why I keep trying",
    "assistant_message": "I'\''m here with you — tell me more."
  }'

json

{
  "user_state": { "mood": 0.28, "energy": 0.41, "trust": 0.40, "sentiment": 0.33 },
  "risk":       { "level": "none", "flags": [] },
  "alerts":     []
}

observe() never blocks and needs no onboarding

/observe runs on heuristics — it works the moment you have a key, before you configure any model. Use it for frictionless monitoring on top of your own chatbot.

3. Process a message

Let Humane run the full pipeline and generate the reply. Requires a configured LLM (see the 409 note below).

bash

curl -X POST https://humaneai.vaarak.com/api/sdk/process \
  -H "Content-Type: application/json" \
  -H "X-API-Key: hx_your_key" \
  -H "Idempotency-Key: req_8f3c9a1b4d" \
  -d '{
    "user_id": "u_8f2",
    "message": "I'\''m anxious about tomorrow",
    "channel": "web_app",
    "metadata": { "plan": "pro" }
  }'

409 onboarding_required

If the tenant has not finished onboarding (no LLM provider + model configured),/process returns 409 with body {"code": "onboarding_required"}. Fall back to /observe (which never requires onboarding) or finish setup. /observe itself never returns this error.

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.

4. Process response shape

json

{
  "response": "I hear you — tell me what's weighing heaviest right now.",
  "user": {
    "id": "u_8f2",
    "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": [],
  "memory": { "total_stored": 18, "interaction_count": 7 }
}

5. Human takeover (REST)

The takeover lifecycle is four endpoints — open a session, send operator messages, hand back. All under /api/sdk, all authed with X-API-Key. The {user_id} in the path is your external id.

bash

# Open a session (first operator wins; a second start returns the same session).
curl -X POST https://humaneai.vaarak.com/api/sdk/takeover/u_8f2 \
  -H "Content-Type: application/json" -H "X-API-Key: hx_your_key" \
  -d '{ "operator_id": "op_1", "operator_name": "Dana" }'

# Inject an operator-authored turn (409 if no active session).
curl -X POST https://humaneai.vaarak.com/api/sdk/takeover/u_8f2/messages \
  -H "Content-Type: application/json" -H "X-API-Key: hx_your_key" \
  -d '{ "body": "Hey, it'\''s Dana — I'\''m here." }'

# Hand the conversation back to the AI.
curl -X POST https://humaneai.vaarak.com/api/sdk/takeover/u_8f2/release \
  -H "Content-Type: application/json" -H "X-API-Key: hx_your_key" \
  -d '{ "handback_message": "Handing you back to the assistant." }'

While a takeover is active

/process responses carry suppress_ai: true, a takeover block, and pending_operator_messages — your bot renders those instead of generating an AI reply. Full contract in Concepts → Human Takeover.

6. Stream tokens (SSE)

bash

curl -N -X POST https://humaneai.vaarak.com/api/sdk/process/stream \
  -H "Content-Type: application/json" \
  -H "X-API-Key: hx_your_key" \
  -d '{"user_id":"u_8f2","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]

7. Durable history

bash

# Read
curl -H "X-API-Key: hx_..." \
  "https://humaneai.vaarak.com/api/sdk/history/u_8f2?limit=200"

# Right-to-erasure
curl -X DELETE -H "X-API-Key: hx_..." \
  "https://humaneai.vaarak.com/api/sdk/history/u_8f2"

8. 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.

9. 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: Observe