Early accessDevelopers

From API key to first alert in one sitting

Install the SDK, send one call and you'll see each user's state and risk. Add gates, takeovers and webhooks when you're ready. Every example here uses the real Python and JavaScript SDKs.

pip install humane-ai · npm install @humane-ai/sdk

POST /api/sdk/process/stream

data: {"type":"metadata","data":{"user":{"mood":0.31},
       "safety":{"action":"PROCEED"},"timing":{"delay_ms":4200}}}

data: {"type":"token","data":{"content":"That"}}
data: {"type":"token","data":{"content":" sounds"}}
data: {"type":"token","data":{"content":" hard."}}

data: [DONE]
metadata firsttokensblocked ends the stream
Illustration of a streamed response
Quickstart

Install and make your first call

Get an hx_ key from the dashboard after verifying your email. The SDKs read nothing else; keep the key in an environment variable.

python
pip install humane-ai          # Python 3.10+

import os
from humane_ai import HumaneClient

client = HumaneClient(api_key=os.environ["HUMANE_API_KEY"])

# After your own model has replied, send the turn to Humane
r = client.observe(
    user_id="user_42",                     # your stable id for this user
    user_message="honestly I don't know why I keep trying",
    assistant_message=reply,               # optional: what your model said
)

print(r.user_state.mood)   # 0.0 to 1.0, lower is lower mood
print(r.risk.level)        # "none" | "elevated" | "critical"
print(r.risk.flags)        # e.g. ["self_harm"]
print(r.alerts)            # raised on elevated or critical risk
Mode 1

Observe: monitor the model you run

Send each completed turn. observe() works without a configured model and fires safety.flagged on elevated or critical risk.

python
import os
from humane_ai import HumaneClient

client = HumaneClient(api_key=os.environ["HUMANE_API_KEY"])

# After your own model has replied, send the turn to Humane
r = client.observe(
    user_id="user_42",                     # your stable id for this user
    user_message="honestly I don't know why I keep trying",
    assistant_message=reply,               # optional: what your model said
)

print(r.user_state.mood)   # 0.0 to 1.0, lower is lower mood
print(r.risk.level)        # "none" | "elevated" | "critical"
print(r.risk.flags)        # e.g. ["self_harm"]
print(r.alerts)            # raised on elevated or critical risk
Mode 2

Proxy: wrap your client, or let Humane run the model

wrap() keeps your existing call and skips the model entirely on BLOCK. process() needs a configured model; without one it returns 409 onboarding_required, so fall back to observe().

python
import os
from openai import OpenAI
from humane_ai import wrap

# One line: every chat.completions.create() now goes through Humane first
client = wrap(OpenAI(), humane_key=os.environ["HUMANE_API_KEY"])

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "I'm really struggling with this"}],
    user="user_42",            # a stable id for this end user
)

print(resp.choices[0].message.content)
print(resp.humane.safety.action)    # "PROCEED" | "HOLD" | "BLOCK"
print(resp.humane.user.mood)        # this user's mood, 0.0 to 1.0
print(resp.humane.analysis.reasons) # the phrases behind the reading
Mode 3

Inject: let a person speak through your bot

During a takeover, process() returns suppress_ai with the operator's pending messages. If you deliver through your own stack, handle the takeover webhooks instead.

python
r = client.process(user_id="user_88", message=text)

if r.raw.get("suppress_ai"):
    # A person has taken over: show their messages, not an AI reply
    for m in r.raw.get("pending_operator_messages", []):
        send_to_user("user_88", m["body"])
else:
    send_to_user("user_88", r.response)
Events

The event catalogue

Subscribe by name, by the proactive.* family, or to * for everything. Unknown names are rejected when you subscribe.

Safety

safety.flagged carries risk_level, flags and source. safety.hold and safety.blocked fire when a gate acts.

Proactive

proactive.triggered plus one event per trigger, task reminders and escalations, and your policy events.

Takeover

takeover.started, takeover.message, takeover.released and takeover.expired, with the operator's details.

Responses

response.ready and interaction.processed for asynchronous consumers of every processed message.

Monitoring

anomaly.detected, experiment.started, experiment.concluded and engine.config_changed.

Account

user.created, end_user.deleted, api_key.created and api_key.revoked.

Signed payloads

Verify every webhook

Each delivery carries X-Humane-Signature: t=<unix>,v1=<hex>, an HMAC-SHA256 of the timestamp, a dot and the raw body, using your webhook secret. The SDK helpers check it and reject anything older than five minutes.

python
import json, os
from fastapi import FastAPI, HTTPException, Request
from humane_ai import verify_webhook_signature

app = FastAPI()
SECRET = os.environ["HUMANE_WEBHOOK_SECRET"]

@app.post("/hooks/humane")
async def humane_hook(request: Request):
    raw = await request.body()
    sig = request.headers.get("X-Humane-Signature")
    if not verify_webhook_signature(SECRET, raw, sig):   # also rejects replays
        raise HTTPException(401, "invalid signature")

    event = json.loads(raw)    # {"event": ..., "timestamp": ..., "data": {...}}
    if event["event"] == "safety.flagged":
        d = event["data"]
        page_on_call(d["user_id"], d["risk_level"], d["flags"], d["source"])
    return {"ok": True}
Reference

Endpoints at a glance

All SDK routes authenticate with the X-API-Key header. The SDKs are thin wrappers over these.

  • POST /api/sdk/observe
  • POST /api/sdk/process and /process/stream
  • GET and POST /api/sdk/memory/{user_id}
  • GET and DELETE /api/sdk/history/{user_id}
  • GET /api/sdk/journey/{user_id}
  • POST /api/sdk/takeover/{user_id}, plus /drafts, /messages, /release
  • GET /api/tasks, POST /api/tasks/{id}/complete and /snooze
  • GET /api/anomalies, POST /api/anomalies/{id}/resolve
  • GET /api/analytics/behavior-score
  • GET /api/privacy/export/{user_id}, DELETE /api/privacy/erase/{user_id}

Developer questions

Something else? Ask us.

Get a key and try it on your own conversations

Early-access teams get a hand with the first integration, from observe() to webhooks.