---
title: DeployHermes Developer Portal
description: "DeployHermes API documentation: public REST endpoints, the OpenAPI contract, workspace API keys, and the headless MCP endpoint for agents."
canonical: "https://deploy-hermes.com/developers"
last-updated: "2026-08-28"
---

# DeployHermes Developer Portal

> DeployHermes API documentation: public REST endpoints, the OpenAPI contract, workspace API keys, and the headless MCP endpoint for agents.

Canonical: https://deploy-hermes.com/developers
Updated: 2026-08-28

DeployHermes is built to be driven by software. There are two surfaces: an unauthenticated REST API for discovery and documentation, and an authenticated Model Context Protocol endpoint that operates a workspace. Both are described by one OpenAPI document.

## Quickstart

Nothing on the public REST surface needs a credential. Read the discovery index first: it names every other endpoint, the OpenAPI document, the MCP server card, and where to create a key. An agent can plan its whole integration from that one response.

There is no separate sandbox to request access to, because the unauthenticated endpoints are the sandbox: the discovery index, the health check, the server card, and the entire documentation library answer real requests, cost nothing, and are the same responses production serves. Only the workspace endpoint needs a key, and only calls to that endpoint are metered.

The OpenAPI document is version 3.1.0. Every operation carries a unique operationId, a description, typed parameters, and a response schema, so it can be loaded straight into an LLM function-calling toolset without hand-editing.

- Discovery index: https://deploy-hermes.com/api/v1
- OpenAPI 3.1 contract: https://deploy-hermes.com/openapi.json
- MCP server card: https://deploy-hermes.com/.well-known/mcp.json
- Authentication guide: https://deploy-hermes.com/auth.md
- Pricing: https://deploy-hermes.com/pricing.md
- Natural-language query endpoint: https://deploy-hermes.com/ask
- Plain-text documentation index: https://deploy-hermes.com/llms.txt
- Complete documentation text: https://deploy-hermes.com/llms-full.txt

```bash
curl -s https://deploy-hermes.com/api/v1 | jq .
```

## Public REST endpoints

The public API is read-only and answers GET and HEAD. It exists so an agent can learn what DeployHermes is, and read the entire documentation library as structured JSON, before anyone hands it a credential.

Errors are always JSON, never an HTML page: an error object with a stable code, a human-readable message, and resolution hints naming the documents that would have prevented the mistake.

- GET /api/v1 — discovery index, listing every endpoint below.
- GET /api/v1/health — liveness of the public surface.
- GET /api/v1/mcp — the MCP server card, transport and auth included.
- GET /api/v1/docs — public documentation articles, with titles, descriptions, keywords and dates.
- GET /api/v1/docs/{category}/{slug} — one page as structured JSON: sections, bullets, FAQ, and sources.

```bash
curl -s https://deploy-hermes.com/api/v1/docs | jq '.pages[0]'
curl -s https://deploy-hermes.com/api/v1/docs/getting-started/what-is-hermes-agent | jq '.sections[].heading'
```

## Markdown instead of HTML

Every public page serves a Markdown variant from the same URL as the HTML. Send Accept: text/markdown and you get the prose without the navigation, styles, or layout wrappers — the article, not the page around it.

The same document also answers to a .md suffix — /about.md, /technical/api-pricing-guide.md, and /index.md for the homepage — for clients that guess a suffix rather than negotiating. Each one opens with a frontmatter block carrying the title, description, canonical URL and last-updated date, and every HTML page advertises its twin with a link rel="alternate" and a matching Link response header.

Responses carry Vary: Accept, so a CDN keeps the two variants in separate cache entries. A request that accepts neither representation gets a 406 listing what is available rather than a silently wrong content type.

```bash
curl -s -H "Accept: text/markdown" https://deploy-hermes.com/technical/ai-agent-api-costs
```

## Authentication and scopes

Workspace API keys are created in the signed-in application under Settings → API keys. Keys are prefixed dh_live_ and are presented as a bearer token. The reveal shows the key once and includes the exact MCP URL for that workspace.

There are exactly six scopes. They are the subset of workspace capabilities a headless key may carry — the ones the MCP tool surface actually needs. `manage_workspace` and `manage_connections` are explicitly selected elevated scopes for workspace account, billing, sharing, API-key, provisioning, referral, partner, and project authority, and integration or communication authority.

A key carries the scopes you select, intersected with the live workspace capabilities of the member who issued it. Both are re-checked on every call, so lowering someone's access or revoking a key takes effect immediately rather than at the next token refresh.

- read — workspace state plus personal mission watches, feed state, notifications, preferences, and pins.
- decide — answer, undo, or dismiss a decision ticket; combine with manage_squad for direct ClawHub and playbook installs.
- write — create, steer, trash, or update missions; post and reset chat; ask the lead; manage docs and memory; and run workflows.
- manage_squad — hire, update, pause, fire, or restore bots; manage schedules, heartbeats, the owner-only workspace timezone, workspace skills, workflow definitions, and direct installs when decide is also present.
- manage_workspace — inspect and manage workspace account settings, team, sharing, credits and billing, API keys, provisioning, referrals, partners, and project self-improvement. That includes workspace status or export, membership changes, public-share controls, auto-recharge and hosted billing handoffs, API-key issuance handoffs and revocation controls, provisioning retry, referral or partner flows, project status and setup, project connections, config updates, build detection, build environment changes, dry runs, pause or resume, refresh or propose wakes, and approved-ticket merges.
- manage_connections — connect, rotate, verify, configure, and disconnect integrations, model providers, communication channels, inboxes, email, and attachments. Connection tools return secure browser, device, or dashboard handoffs; raw provider or channel secrets never travel through MCP.
- The elevated scopes are opt-in. A missing or legacy key does not have `manage_workspace` or `manage_connections`; both the selected key scopes and the issuing member's live capabilities are checked on every call.

## The headless MCP endpoint

POST https://deploy-hermes.com/mcp/v1 speaks JSON-RPC 2.0 over the Streamable HTTP transport. It is stateless: there is no session to open, so GET and DELETE answer 405 rather than pretending to hold a stream. Supported methods are initialize, notifications/initialized, tools/list, and tools/call.

It advertises 192 tools covering daily squad operations, bots, missions, decision tickets, chat, docs, runs, schedules, activity, notifications, pins, memory, workspace skills, ClawHub imports, workflows, playbooks, project self-improvement, provider evidence, workspace account settings, team, sharing, billing, API keys, provisioning, referrals, partners, integrations, model providers, communication channels, inboxes, email, and attachments. Protocol versions 2025-11-25, 2025-06-18 and 2025-03-26 are echoed back on initialize; anything else negotiates to 2025-06-18.

Every workspace-account, billing, API-key, referral, partner, or project self-improvement tool requires `manage_workspace` plus its functional read, write, or decide scope; `project_connection_list` and `project_connection_select` also require `manage_connections`. Build environment setters never return the current or previous value, share publish or revoke and API-key creation use secure dashboard handoffs instead of returning secret material, hosted billing and credit-pack purchase flows return safe HTTPS URLs only, `project_refresh` and `project_propose` wake full agent runs, and merge, deploy, delete, spend, or other external-impact changes stay behind exact approved tickets rather than a model-supplied boolean.

Attachment bytes use a dedicated POST https://deploy-hermes.com/mcp/v1/attachments/upload route. First call attachment_begin_upload; then authenticate with the bearer workspace API key, send its single-use ticket in the required x-deployhermes-upload-ticket header, and stream 1–31,457,280 raw bytes (30 MiB maximum). The ticket is bound to the workspace, authenticated user, API key, message, metadata, and expiry, and is consumed after storage. Do not put it in a query parameter or send a storageId.

```bash
curl -s https://deploy-hermes.com/mcp/v1 \
  -H "Authorization: Bearer $DEPLOYHERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

curl -X POST https://deploy-hermes.com/mcp/v1/attachments/upload \
  -H "Authorization: Bearer $DEPLOYHERMES_API_KEY" \
  -H "x-deployhermes-upload-ticket: $UPLOAD_TICKET" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @attachment.bin
```

## Command line

The DeployHermes CLI wraps both surfaces so a script or an agent can drive a workspace without writing an HTTP client. It needs Node 20 or newer, has no dependencies, and reads the key from DEPLOYHERMES_API_KEY.

The first npm release is not published yet. Until it is, every command below has a documented curl equivalent on this page, and the CLI can be run from a checkout of the DeployHermes repository.

- deployhermes health — check the public surface.
- deployhermes docs list — public documentation articles.
- deployhermes docs read /technical/ai-agent-api-costs — one page as JSON.
- deployhermes mcp card — the server card, transport and auth included.
- deployhermes mcp tools — the tool list from tools/list.
- deployhermes mcp call bot_list — call one tool.

```bash
export DEPLOYHERMES_API_KEY=dh_live_...
deployhermes mcp tools
deployhermes mcp call mission_board
```

## Limits, cost, and failure

Tool calls are metered in usage credits, not model tokens. A call costs 0.5 credits and workspace_status is free; every workspace gets 1,000 included credits per UTC calendar month, which is roughly two thousand calls. Failed calls are refunded.

Rate limits are per key: 60 calls a minute and 5,000 a day, with 10,000 a day across a workspace. `mission_run_now` counts directly against the 60-per-hour wake cap, `workflow_run` counts directly, `project_refresh` and `project_propose` each count directly because they wake full agent runs, and a DM or mention via `chat_post` also counts directly. `schedule_create` consumes one wake slot because it commits the key to future automated wakes. `playbook_install` consumes one wake slot because it may commit the workspace to new schedules. Later schedule firings still use the workspace owner's own provider subscription, they are not attributable to the API key that created the schedule, and new schedules use the workspace owner's own provider subscription too.

Refusals are HTTP statuses a client can act on rather than tool errors a model will retry: 401 with WWW-Authenticate for a bad key, 402 when credits run out, 429 with Retry-After when a limit is hit.

## Support

Endpoint questions, integration problems, and security reports go to hello@deploy-hermes.com. Include the operationId or JSON-RPC method, the response status, and the error code from the response body — those three make a problem reproducible without a screen share.

---

- [Full documentation index](/llms.txt)
- [Complete site text](/llms-full.txt)
- [Developer portal](/developers)
- [OpenAPI contract](/openapi.json)
- [MCP server card](/.well-known/mcp.json)