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]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.
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 riskThree ways to connect, in order of effort
1. Observe
ObserveCall observe() after your model replies. You get state and risk back, and alerts go out. Nothing sits in your reply path.
Learn more2. Proxy
Guardwrap() your OpenAI-style client, or call process() and let Humane run your model. Every reply passes the gates first.
Learn more3. Inject
TakeoverHandle takeover webhooks, or read pending operator messages from process(), so a person can speak through your bot.
Learn moreObserve: monitor the model you run
Send each completed turn. observe() works without a configured model and fires safety.flagged on elevated or critical risk.
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 riskProxy: 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().
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 readingInject: 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.
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)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.
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.
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}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.
