Docs/Developers
REST API
The /api/v1 control plane behind the dashboard, CLI, and MCP server — everything Hermes does, over plain HTTPS with bearer auth.
https://tryhermes.dev/api/v1Authentication
Send a bearer token in the Authorization header. Two kinds work:
| Token | Scope | Where to get it |
|---|---|---|
hk_... API key | Pinned to one organization. | Settings → API keys in the dashboard. |
cli_... session | Your whole account, all organizations. | Minted by hermes auth login or an MCP OAuth connection. |
With an account-level session, pass X-Hermes-Org: <org-slug> to pick the organization per request (optional if you belong to exactly one).
curl https://tryhermes.dev/api/v1/triggers \
-H "Authorization: Bearer hk_..."Resources
| Resource | Endpoints |
|---|---|
| Connections | GET/POST /connections, GET/DELETE /connections/{id}, GET .../schema, POST .../inspect-schema, POST .../query, POST /connections/csv (multipart upload). |
| Triggers | GET/POST /triggers, GET/PATCH/DELETE /triggers/{id}, POST .../run, POST .../preview. |
| Signals | GET /signals, GET/PATCH /signals/{id}, POST /signals/run, GET /signals/run/{jobId}. |
| Drafts | GET /drafts, GET /drafts/{id}, POST .../approve, POST .../reject, POST /drafts/approve (bulk). |
| Emails | GET /emails, GET /emails/{id} (with delivery + engagement timeline). |
| Templates | GET/POST/PATCH /templates, GET/PATCH/DELETE /templates/{id}, POST /templates/design (AI designer). |
| Senders | GET/POST /senders, GET/PATCH/DELETE /senders/{id}. |
| Domains | GET/POST /domains, GET/DELETE /domains/{id}, POST .../verify, plus DNS planning helpers. |
| Analytics | GET /analytics/overview, GET /analytics/campaign/{trigger_id}. |
| Account | GET /orgs, GET /orgs/{slug}, GET /auth/whoami. |
Two examples
Run a trigger immediately and check its drafts:
curl -X POST https://tryhermes.dev/api/v1/triggers/trg_123/run \
-H "Authorization: Bearer hk_..."
curl "https://tryhermes.dev/api/v1/drafts?trigger_id=trg_123" \
-H "Authorization: Bearer hk_..."Kick off signal discovery and poll it:
curl -X POST https://tryhermes.dev/api/v1/signals/run \
-H "Authorization: Bearer hk_..."
# → { "job_id": "..." }
curl https://tryhermes.dev/api/v1/signals/run/JOB_ID \
-H "Authorization: Bearer hk_..."Long-running operations — trigger runs, discovery passes — return a job ID you can poll instead of holding the connection open.
Conventions
- Read-only queries only.
POST /connections/{id}/queryaccepts single read statements and runs them in a read-only transaction with a timeout — the API cannot write to your data source, by construction. - Approval semantics match the dashboard. Approving a draft queues it for delivery; rejecting releases the person for future runs. There is no "send" endpoint that bypasses the draft lifecycle.
- Same surface everywhere. The MCP server exposes these endpoints one-for-one as tools, and the CLI wraps them one-for-one as commands — anything you learn here transfers.
These docs are agent-readable too: append .md-style paths under
/md/ or fetch /llms.txt for a machine-friendly
index of every page.