Introduction

Auth, mailbox tools, and errors. MCP is the fastest path for agents; REST covers the same work over HTTP.

Start here

MCP

OAuth in the editor, or a key for scripts.

Inbox Skills

npx skills add Humaner-inc/Inbox-skills

Authentication

Bearer API keys.

API keys

Create and scope keys in the dashboard.

Errors

Status codes and shapes.

Base URL

https://app.humaner.io

Endpoints

Method	Path	Purpose
POST	/api/mcp	MCP streamable HTTP (mailbox tools)
POST	/api/v1/chat	Send a message, stream the reply
GET	/api/v1/agents/{publicId}	Fetch agent name, character, greeting
POST	/api/v1/visitors/identify	Attach a visitor ID for cross-session memory
POST	/api/v1/handoff/ticket	Create a handoff ticket

Authentication

REST takes a scoped Bearer API key. MCP in Cursor, Claude, or VS Code uses OAuth — add the URL and sign in once. Same key still works on MCP for scripts.

Authorization header

Authorization: Bearer hm_live_xxxxxxxx

Response conventions

Endpoint	Response type
POST /api/v1/chat	text/event-stream (SSE). See the Chat reference
All others	application/json

Errors are always { "error": "message" }. Full table detailed on Errors page.

Plan gating

API access needs Custom or Humaner.