Overview & authentication

Everything you can do in the ExoHuman web app is available through a REST API on your instance. The same instance also exposes an MCP server for AI clients and a CLI for the terminal.

Base URL

https://<subdomain>.exohuman.cc/api

All examples use https://acme.exohuman.cc. The full, interactive OpenAPI reference for your exact version is served by your instance to signed-in administrators.

Authentication

Every request carries a bearer token:

Authorization: Bearer <token>

You can use either kind of token:

Token	Get it from	Lifetime	Best for
API key (`exohuman_mcp_…`)	Settings → My account → Connect my tools	Until revoked	Scripts, CI, integrations
Session token (JWT)	Email-code sign-in (below)	7 days	Short-lived interactive tools

Both act with your permissions: you see and control exactly the agents you could in the web app. Prefer API keys for automation — they don’t expire and can be revoked individually, and each call is attributed to the key in the audit log.

Signing in with an email code

curl -X POST https://acme.exohuman.cc/api/auth/email/request \
  -H 'Content-Type: application/json' -d '{"email":"[email protected]"}'

curl -X POST https://acme.exohuman.cc/api/auth/email/verify \
  -H 'Content-Type: application/json' -d '{"email":"[email protected]","code":"123456"}'
# → {"access_token":"eyJ…","token_type":"bearer", …}

If the account requires two-factor authentication, the verify step does not return an access_token; finish the second factor interactively or use an API key instead. Scripts should always check that a token was actually issued.

Conventions

Request and response bodies are JSON.
Agents are addressed by their name (slug), e.g. /api/agents/sales-assistant.
Errors return a status code and {"detail": "…"}. 401 means missing or invalid credentials, 403 not permitted, 404 not found or not visible to you, 409 a conflicting state (for example the agent is busy), 422 an invalid body, 429 rate limited.
Timestamps are ISO 8601 in UTC.

Idempotency

Endpoints that start work — /chat, /task, schedule triggers, webhooks, outbound calls, metric recording — accept an Idempotency-Key header. Repeating a request with the same key returns the first result (with an X-Idempotent-Replay header) instead of running it again. Use a fresh key when you deliberately want a new run, for example after a failure.

What’s in this reference

Agents — create, list, start, stop, configure.
Chat & tasks — talk to agents and run tasks.
Schedules — cron schedules and their runs.
MCP tools — the tools available to MCP clients and agents.
CLI — the exohuman command-line client.
Webhooks — trigger schedules from external systems.