API Reference

Base URL: https://api.h.work (prod) / https://api.h852.work (staging)

Auth: Authorization: Bearer <jwt> on all protected endpoints unless noted.

Global rate limit: 100 req/min per IP. Auth endpoints: 10 req/min.

---

Health

Method	Path	Auth	Description
GET	/health	None	Liveness probe — returns 200 if service is up
GET	/ready	None	Readiness probe — checks DB + agent connectivity
GET	/metrics	Network policy	Prometheus metrics (internal only)

---

Auth

Method	Path	Auth	Description
POST	/auth/register	None	Self-service: create org + first admin user
POST	/auth/login	None	Returns JWT with userId, email, platformRole, orgMemberships
POST	/auth/demo-login	None	Demo backdoor (DEMO_MODE=true only)
POST	/auth/orgs	Superadmin	Create org with admin user
POST	/auth/accept-invite/:token	None	Accept invite + set password → JWT
POST	/orgs/:orgId/invites	OrgAdmin	Invite user by email
DELETE	/orgs/:orgId/members/:userId	OrgAdmin	Remove user from org
GET	/orgs/:orgId	JWT	Org details
GET	/orgs/:orgId/members	OrgAdmin	List org members
GET	/orgs/:orgId/quota	JWT	Hourly message quota status

2FA

Method	Path	Auth	Description
POST	/auth/2fa/setup	JWT	Generate TOTP secret + QR code URI
POST	/auth/2fa/verify	JWT	Verify TOTP code and enable 2FA

Superadmin Auth Tools

Method	Path	Auth	Description
POST	/auth/bootstrap-superadmin	None (once)	Promote first user if no superadmin exists
PATCH	/admin/users/:id/role	Superadmin	Update platformRole
PATCH	/admin/users/:id/password	Superadmin	Reset password

OTP Flow (Onboarding)

Method	Path	Auth	Description
GET	/invites/validate	None	Validate invite token
POST	/auth/send-invite-otp	None	Send email OTP
POST	/auth/verify-invite-otp	None	Verify OTP → create/activate account

---

Conversations

Rate limit: 100 req/min per PRD §14.

Method	Path	Auth	Description
POST	/conversations	JWT	Create conversation
GET	/conversations	JWT	List conversations (filter: orgId)
GET	/conversations/search	JWT	Full-text search (q, orgId, limit, offset)
GET	/conversations/:id	JWT	Fetch conversation + messages (paginated)
POST	/conversations/:id/messages	JWT	Send message
POST	/conversations/:id/messages/stream	JWT	Stream agent response as SSE
POST	/conversations/:id/assign-agent	JWT	Reassign or rename agent

---

Expert Queue

Method	Path	Auth	Description
GET	/expert-queue	Expert	List queue items (filter: status, orgId)
GET	/expert-queue/:id	Expert	Fetch single queue item
POST	/expert-queue/:id/suggest	Expert	Get fresh AI suggestion for item
POST	/expert-queue/:id/respond	Expert	Send response (approve/edit/write own)
POST	/expert-queue/:id/resolve	Expert	Resolve with satisfaction score
PATCH	/expert-queue/:id/status	Expert	Update status (pending/in_progress/resolved)
POST	/expert-queue/:id/defer	Expert	Defer item by X hours
POST	/expert-queue/:id/add-note	Expert	Add internal note
POST	/expert-queue/:id/corrections	Expert	Submit correction for learning loop
GET	/expert/orgs	Expert	Get Expert's available orgs

Removed (2026-05-03): /expert-queue/:id/reassign, /expert/pools, /pools, /expert/pools/:id/members — expert pool model deleted. Expert ↔ Org assignment is now direct via org_experts.

---

Onboarding

All onboarding endpoints use a token (from the invitation email) instead of JWT auth.

Client-Facing (Phase 2 Wizard)

Method	Path	Auth	Description
POST	/onboarding/:token/verify-email	Token	Send OTP to admin email
POST	/onboarding/:token/confirm-otp	Token	Verify OTP → session JWT
POST	/onboarding/:token/set-credentials	Token	Set password (+ optional 2FA)
POST	/onboarding/:token/profile	Token	Save name, title, phone
GET	/onboarding/:token/org	Token	Org details for wizard
GET	/onboarding/:token/specialist	Token	Assigned Specialist card
POST	/onboarding/:token/confirm-slug	Token	Finalize and reserve slug
GET	/onboarding/:token/whitelist	Token	List email whitelist entries
POST	/onboarding/:token/whitelist	Token	Add entry to whitelist
DELETE	/onboarding/:token/whitelist/:id	Token	Remove whitelist entry
POST	/onboarding/:token/invite-members	Token	Invite multiple Client Members
POST	/onboarding/:token/complete	Token	Finalize onboarding (Step 2.6)

Public Onboarding Endpoints

Method	Path	Auth	Description
GET	/orgs/slug-check	None	Real-time slug availability check
GET	/invitations/:token/validate	None	Validate invite token, return org slug
GET	/client/trial-info	JWT	Trial countdown for client portal

---

Organizations (Account Manager)

Method	Path	Auth	Description
POST	/orgs	AM	Create org (status: pending_am_setup)
GET	/am/orgs	AM	List AM's assigned orgs
GET	/am/orgs/:orgId	AM	Org detail
PATCH	/am/orgs/:orgId	AM	Update company info
GET	/am/orgs/:orgId/phase0-status	AM	Phase 0 validation checklist
POST	/am/orgs/:orgId/invite	AM	Send client invitation (Phase 0 gate check)
POST	/am/orgs/:orgId/invite/resend	AM	Resend invitation (fresh 7-day token)
DELETE	/am/orgs/:orgId/invite	AM	Revoke invitation
GET	/am/specialists	AM	List available specialists
GET	/am/specialists/:id	AM	Specialist detail
POST	/am/orgs/:orgId/specialist	AM	Assign specialist to org (1:N)
DELETE	/am/orgs/:orgId/specialist	AM	Unassign specialist

Specialist Change Requests

Method	Path	Auth	Description
POST	/orgs/:orgId/specialist-change-requests	OrgAdmin	Client requests different specialist
GET	/orgs/:orgId/specialist-change-requests	AM	AM views pending requests
PATCH	/orgs/:orgId/specialist-change-requests/:id	AM	AM fulfills or declines request

Superadmin Org Endpoints

Method	Path	Auth	Description
POST	/organizations	Superadmin	Create org
GET	/superadmin/orgs	Superadmin	List all orgs (legacy — prefer /ops/orgs)
GET	/experts	Superadmin	List all experts

---

Admin

Method	Path	Auth	Description
GET	/admin/members	OrgAdmin	List org members
POST	/admin/members/invite	OrgAdmin	Invite member
GET	/admin/billing	OrgAdmin	Org billing status
GET	/admin/quota	OrgAdmin	Org quota usage
POST	/admin/impersonate/am/:userId	Superadmin	Start silent AM impersonation
DELETE	/admin/impersonate	Superadmin	End impersonation session
POST	/admin/orgs/:orgId/restore	Superadmin	Restore archived stale org

---

Channels

Inbound Webhooks

Method	Path	Auth	Description
POST	/channels/slack/events	HMAC-SHA256	Slack Events API webhook
POST	/channels/email/inbound	None (Cloudflare)	Cloudflare Email Routing inbound webhook
POST	/channels/whatsapp/inbound	Twilio HMAC-SHA1	WhatsApp inbound (Twilio webhook)
POST	/channels/teams/webhook	Bot Framework	Teams webhook (stub)
GET	/channels/wechat/webhook	None	WeChat verification challenge
POST	/channels/wechat/webhook	WeChat sig	WeChat inbound (stub)
POST	/channels/telegram/webhook	HMAC-SHA256	Telegram Bot API updates

Channel Admin

Method	Path	Auth	Description
GET	/orgs/:orgId/channels/status	OrgAdmin	Health status for all channels
GET	/orgs/:orgId/channels/webhook-urls	OrgAdmin	Webhook URLs to configure in channel dashboards

Integration Credentials

Method	Path	Auth	Description
POST	/orgs/:orgId/integrations	OrgAdmin	Create/upsert channel credentials
GET	/orgs/:orgId/integrations	OrgAdmin	List integrations (values masked)
DELETE	/orgs/:orgId/integrations/:id	OrgAdmin	Delete integration
POST	/orgs/:orgId/integrations/:id/test	OrgAdmin	Test connection

---

Billing

Method	Path	Auth	Description
POST	/billing/subscriptions	JWT	Create Stripe subscription
GET	/billing/subscriptions	Superadmin	List all subscriptions
GET	/billing/subscriptions/:orgId	JWT	Get org subscription
DELETE	/billing/subscriptions/:orgId	Superadmin	Cancel subscription
POST	/billing/webhooks	Stripe sig (raw body)	Stripe webhook handler

---

Agentic Tasks

Method	Path	Auth	Description
POST	/agentic/tasks	JWT	Create agentic task with step plan
GET	/agentic/tasks	JWT	List tasks by org (filter: status=pending_approval)
GET	/agentic/tasks/:id	JWT	Get task + full plan
POST	/agentic/tasks/:id/steps/:stepId/approve	Expert	Approve a step
POST	/agentic/tasks/:id/steps/:stepId/reject	Expert	Reject step with feedback

---

Agents

Method	Path	Auth	Description
GET	/orgs/:orgId/agents	JWT	List org agents (filter: role)
POST	/orgs/:orgId/agents	OrgAdmin	Create agent for org
DELETE	/orgs/:orgId/agents/:id	OrgAdmin	Remove agent

---

Tools

Method	Path	Auth	Description
POST	/tools/execute	PLATFORM_API_TOKEN	Internal: execute tool (shopify_query, amazon_query)
GET	/orgs/:orgId/tool-permissions	OrgAdmin	List enabled tools
PUT	/orgs/:orgId/tool-permissions/:toolName	OrgAdmin	Enable/disable tool with optional config

---

Analytics

Method	Path	Auth	Description
GET	/analytics/summary	JWT	Aggregate analytics (superadmin: all orgs; org: scoped)

---

Audit Log

Method	Path	Auth	Description
GET	/audit-log	JWT	Paginated audit log (filter: from, to, entity_type, limit, cursor)

---

Learning

Method	Path	Auth	Description
GET	/learning/corrections	Superadmin	List corrections (filter: role)
GET	/learning/corrections/stats	Superadmin	Aggregated correction stats by type

---

Users

Method	Path	Auth	Description
GET	/users/me	JWT	Current user profile
POST	/users/:id/hp-verify	JWT	Humanity Protocol credential verification (stub)