Hermes Hub External REST API Contract

Hermes Hub exposes an HTTP API for managing hosted Hermes Agent tenants, their runs, shared storage, skills, cron jobs, credentials, and operator policy.

This document describes the client-facing contract. It intentionally omits host deployment internals and private runtime implementation details.

Base URL

Use the Hub URL provided by your operator:

https://<hub-host>

All management endpoints are rooted under /v1 unless otherwise noted.

Authentication

Management endpoints require:

Authorization: Bearer <token>

Webhook endpoints use the relevant upstream provider verification scheme. Tenant-runtime callback endpoints are private to tenant runtimes and are not general client APIs.

Response Format

Successful responses are JSON unless an endpoint explicitly streams events or downloads file bytes.

Errors use problem-style JSON with stable fields such as:

{
  "code": "invalid_argument",
  "message": "human-readable detail",
  "status": 400
}

Core Endpoints

Health and Metadata

Method	Path	Purpose
`GET`	`/v1/healthz`	Liveness check.
`GET`	`/v1/readyz`	Readiness check.
`GET`	`/v1/version`	Hub version and runtime metadata.

Tenants

Method	Path	Purpose
`GET`	`/v1/tenants`	List tenants.
`POST`	`/v1/tenants`	Create and provision a tenant.
`GET`	`/v1/tenants/{tenantId}`	Get one tenant.
`PATCH`	`/v1/tenants/{tenantId}`	Update tenant metadata and desired settings.
`DELETE`	`/v1/tenants/{tenantId}`	Delete one tenant.
`GET`	`/v1/tenants/{tenantId}/access`	Read tenant access state.
`PUT`	`/v1/tenants/{tenantId}/access`	Set tenant access state.

Tenant IDs are path identifiers. Treat them as opaque strings that must match the API validation rules.

Tenant Agent Lifecycle

Method	Path	Purpose
`GET`	`/v1/tenants/{tenantId}/agent`	Get current tenant agent state.
`POST`	`/v1/tenants/{tenantId}/agent/start`	Start or wake the tenant agent.
`POST`	`/v1/tenants/{tenantId}/agent/stop`	Stop the tenant agent.
`POST`	`/v1/tenants/{tenantId}/agent/restart`	Restart the tenant agent.
`GET`	`/v1/tenants/{tenantId}/agent-card`	Return the tenant’s public A2A agent card.

Runs and Events

Method	Path	Purpose
`POST`	`/v1/tenants/{tenantId}/runs`	Start a Hermes Agent run.
`GET`	`/v1/tenants/{tenantId}/runs/{runId}`	Get run status and metadata.
`GET`	`/v1/tenants/{tenantId}/runs/{runId}/events`	Stream run events.
`POST`	`/v1/tenants/{tenantId}/runs/{runId}/stop`	Stop a running run.
`POST`	`/v1/tenants/{tenantId}/runs/{runId}/approval`	Resolve a pending run approval.

Run event streams are long-lived responses. Clients should handle reconnects and terminal run states.

Tenant Files

Method	Path	Purpose
`GET`	`/v1/tenants/{tenantId}/files`	List tenant-visible file roots and directories.
`GET`	`/v1/tenants/{tenantId}/files/content`	Read text-previewable file content.
`GET`	`/v1/tenants/{tenantId}/files/download`	Download one tenant-visible file.

Only tenant-visible roots are exposed. Secrets, private runtime state, and other tenants’ private areas are not part of the file API.

Tenant Environment Keys

Method	Path	Purpose
`GET`	`/v1/tenants/{tenantId}/env`	List tenant-scoped environment key names and metadata.
`PUT`	`/v1/tenants/{tenantId}/env/{name}`	Set one accepted tenant-scoped key.
`DELETE`	`/v1/tenants/{tenantId}/env/{name}`	Remove one tenant-scoped key.

Only accepted tenant-scoped, secret-style names may be set. Hub-managed runtime keys are reserved.

Skills

Method	Path	Purpose
`GET`	`/v1/tenants/{tenantId}/skills`	List installed tenant skills.
`GET`	`/v1/tenants/{tenantId}/skills/{category}/{skill}/files`	List files for one skill.
`GET`	`/v1/tenants/{tenantId}/skill-files/{skillPath}`	Read one skill file.
`PUT`	`/v1/tenants/{tenantId}/skills/{skillName}/state`	Set skill enabled/disabled state.

Agent Cron

Method	Path	Purpose
`GET`	`/v1/tenants/{tenantId}/agent-cron`	List tenant agent cron jobs.
`POST`	`/v1/tenants/{tenantId}/agent-cron`	Create an agent cron job.
`GET`	`/v1/tenants/{tenantId}/agent-cron/{jobId}`	Get one cron job.
`PATCH`	`/v1/tenants/{tenantId}/agent-cron/{jobId}`	Update one cron job.
`DELETE`	`/v1/tenants/{tenantId}/agent-cron/{jobId}`	Delete one cron job.
`POST`	`/v1/tenants/{tenantId}/agent-cron/{jobId}/pause`	Pause one cron job.
`POST`	`/v1/tenants/{tenantId}/agent-cron/{jobId}/resume`	Resume one cron job.
`POST`	`/v1/tenants/{tenantId}/agent-cron/{jobId}/run`	Trigger one cron job immediately.

The cron job schema is owned by the tenant agent runtime. Hub passes job definitions through and returns the runtime response.

Method	Path	Purpose
`GET`	`/v1/share-groups`	List share groups.
`POST`	`/v1/share-groups`	Create a share group.
`GET`	`/v1/share-groups/{groupId}`	Get one share group.
`PATCH`	`/v1/share-groups/{groupId}`	Update one share group.
`DELETE`	`/v1/share-groups/{groupId}`	Delete one share group.
`PUT`	`/v1/share-groups/{groupId}/members/{tenantId}`	Set a member’s access.
`DELETE`	`/v1/share-groups/{groupId}/members/{tenantId}`	Remove a member.
`GET`	`/v1/tenants/{tenantId}/shares`	List shares visible to a tenant.

Share file operations are scoped by tenant and share group:

/v1/tenants/{tenantId}/shares/{groupId}/list
/v1/tenants/{tenantId}/shares/{groupId}/read
/v1/tenants/{tenantId}/shares/{groupId}/stat
/v1/tenants/{tenantId}/shares/{groupId}/grep
/v1/tenants/{tenantId}/shares/{groupId}/find
/v1/tenants/{tenantId}/shares/{groupId}/write
/v1/tenants/{tenantId}/shares/{groupId}/mkdir
/v1/tenants/{tenantId}/shares/{groupId}/move
/v1/tenants/{tenantId}/shares/{groupId}/remove

Read operations require share membership. Mutating operations require write access to that share.

A2A Edge Surfaces

Method	Path	Purpose
`POST`	`/a2a/{tenantId}`	Tenant A2A endpoint.
`GET`	`/a2a/{tenantId}/.well-known/agent.json`	Public agent metadata.
`GET`	`/a2a/{tenantId}/.well-known/agent-card.json`	Public agent card.
`GET`	`/v1/tenants/{tenantId}/a2a-peers`	List introduced peers.
`POST`	`/v1/tenants/{tenantId}/a2a-peers`	Introduce a peer.
`GET`	`/v1/tenants/{tenantId}/a2a-peers/{peerId}`	Get one peer.
`DELETE`	`/v1/tenants/{tenantId}/a2a-peers/{peerId}`	Remove one peer.

Credentials and Secrets

Method	Path	Purpose
`GET`	`/v1/tenants/{tenantId}/a2a-credentials`	Return tenant A2A credentials.
`GET`	`/v1/tenants/{tenantId}/api-credentials`	Return tenant-scoped API credentials.
`POST`	`/v1/tenants/{tenantId}/api-credentials/rotate`	Rotate tenant-scoped API credentials.
`GET`	`/v1/secrets`	List managed secret metadata.
`POST`	`/v1/secrets`	Register a managed secret without returning material.
`GET`	`/v1/secrets/{secretId}`	Return managed secret metadata.
`DELETE`	`/v1/secrets/{secretId}`	Delete managed secret metadata and material.
`POST`	`/v1/secrets/{secretId}:replace-material`	Replace write-only secret material.
`POST`	`/v1/secrets/{secretId}:refresh`	Refresh one OAuth2 secret.
`POST`	`/v1/secrets/{secretId}:rotate`	Rotate one managed API-key secret.
`POST`	`/v1/secrets:refresh-due`	Refresh all due OAuth2 secrets.

Secret material is write-only. Read APIs return metadata and status only.

Flavors, Releases, and Evals

Method	Path	Purpose
`GET`	`/v1/hermes-agent/releases`	List installed agent releases.
`POST`	`/v1/hermes-agent/releases`	Register or install a release.
`GET`	`/v1/hermes-agent/releases/{releaseId}`	Get one release.
`DELETE`	`/v1/hermes-agent/releases/{releaseId}`	Delete an inactive unused release.
`POST`	`/v1/hermes-agent/releases/{releaseId}:activate`	Promote a release.
`GET`	`/v1/flavors`	List flavor catalog.
`POST`	`/v1/flavors`	Install a flavor package.
`GET`	`/v1/flavors/{flavorId}`	Get one flavor catalog entry.
`GET`	`/v1/flavors/{flavorId}/versions/{flavorVersion}`	Get one flavor version.
`DELETE`	`/v1/flavors/{flavorId}/versions/{flavorVersion}`	Delete an unused flavor version.
`GET`	`/v1/flavors/{flavorId}/versions/{flavorVersion}/contents`	Return renderable flavor contents.
`GET`	`/v1/flavors/{flavorId}/versions/{flavorVersion}/eval-suites`	List flavor eval suites.
`POST`	`/v1/flavors/{flavorId}/versions/{flavorVersion}/eval-runs`	Start an eval run.
`POST`	`/v1/flavors/{flavorId}/versions/{flavorVersion}:deprecate`	Deprecate a flavor version.
`GET`	`/v1/eval-runs`	List eval runs.
`GET`	`/v1/eval-runs/{evalRunId}`	Get one eval run.
`POST`	`/v1/eval-runs/{evalRunId}:cancel`	Cancel an eval run.

Policy and Configuration

Method	Path	Purpose
`GET`	`/v1/agent-policy`	Return hub-wide agent policy.
`PUT`	`/v1/agent-policy`	Replace hub-wide agent policy.
`GET`	`/v1/agent-features`	List known agent features.
`GET`	`/v1/agent-specialization`	Get default hosted-agent specialization.
`PUT`	`/v1/agent-specialization`	Replace default specialization.
`DELETE`	`/v1/agent-specialization`	Disable default specialization.
`GET`	`/v1/tenants/{tenantId}/agent-policy`	Get tenant effective policy and override.
`PUT`	`/v1/tenants/{tenantId}/agent-policy`	Replace tenant policy override.
`DELETE`	`/v1/tenants/{tenantId}/agent-policy`	Delete tenant policy override.
`GET`	`/v1/config/tenant-impact`	Return tenant-impacting config view.
`PATCH`	`/v1/config/tenant-impact`	Stage tenant-impacting config changes.
`POST`	`/v1/config/tenant-impact:apply`	Apply staged config changes.

Metrics and Business Keys

Method	Path	Purpose
`GET`	`/v1/metrics/runs`	List run metrics.
`GET`	`/v1/metrics/runs/{runId}`	Get one run metrics record.
`GET`	`/v1/metrics/schedules`	List schedule metrics.
`GET`	`/v1/metrics/usage/aggregate`	Aggregate usage metrics.
`GET`	`/v1/admin/business-keys`	List business keys.
`POST`	`/v1/admin/business-keys`	Create a business key.
`DELETE`	`/v1/admin/business-keys/{businessKeyId}`	Delete a business key.

Webhooks

Method	Path	Purpose
`GET`	`/webhooks/whatsapp`	Meta WhatsApp webhook verification.
`POST`	`/webhooks/whatsapp`	Meta WhatsApp message events.
`POST`	`/webhooks/telegram`	Telegram Bot API message events.

Webhook bodies are provider-defined.

Non-Client Runtime Callback Endpoints

Paths under /v1/tenant-runtime/{tenantId}/... are reserved for tenant runtime callbacks and hub-managed runtime proxying. External clients should not call them directly unless they are implementing a compatible tenant runtime and have the tenant-runtime credential.