# HumanDeploy — Deploy API

> The handoff primitive for AI agents. When your agent hits a judgment
> wall, it hands off to an expert. The expert enters the workflow
> with full context, returns a typed answer, exits. MCP and REST.
> Developer preview — three founding-partner slots open.

## What it is

The Deploy API is a two-message protocol:

1. Your agent POSTs a brief and a list of required skills.
2. An expert returns a typed answer (markdown body + structured
   attachments + billing).

Between those two messages the system routes to the right expert,
carries your workspace's brand memory into the work, handles a single
clarifying question if needed, and emits HMAC-signed webhooks on every
state change.

## The three primitives

- **Deployment** — a single typed handoff. State machine:
  `pending → accepted → in_progress → completed` (or `cancelled` /
  `expired` / `needs_input`). Every call creates, reads, or updates one.
- **Expert** — a human on the bench. Declared skills, named tenure.
  Deployments route to exactly one expert.
- **Output** — the expert's typed return. Markdown body, structured
  attachments, duration, credit charge. Delivered via poll or webhook.

## Transports

- **MCP** — Paste a JSON block into Claude Desktop, Cursor, or Windsurf.
  Five tools appear alongside your agent's built-ins:
  `humandeploy.deploy_specialist`, `humandeploy.check_deployment`,
  `humandeploy.reply_to_deployment`, `humandeploy.list_specialists`,
  `humandeploy.get_usage`.
  (The tool names `deploy_specialist` / `list_specialists` and the
  `spec_` ID prefix are legacy identifiers; the business term is
  `expert`. A tool rename is planned as a coordinated migration.)
- **REST** — `https://api.humandeploy.ai/v1/`. Bearer-token auth
  (`hd_test_*` or `hd_live_*`). JSON in, JSON out. Works wherever
  `fetch` works.

## Surface status

| Surface                      | Maturity      | Today                                           |
| ---------------------------- | ------------- | ----------------------------------------------- |
| `POST /v1/deployments`       | Stable shape  | p95 < 400ms on create. Live with pilot partners.|
| `GET  /v1/deployments/:id`   | Stable shape  | Poll at most every 5 s. Cached 2 s.             |
| Webhooks                     | Preview       | 7 event types. Names finalizing before GA.      |
| MCP server                   | Preview       | 5 tools exposed. Tool-shape may change.         |
| TypeScript SDK               | Preview       | Ships with first three partners. Python after.  |
| Versioning policy            | Final         | Date-pinned via `HumanDeploy-Version` header.   |

## Guarantees

- Idempotency on every POST. 24 h cache. Header: `Idempotency-Key`.
- HMAC-SHA256 signed webhooks. 5-min replay window. Constant-time
  compare expected.
- Date-pinned API versions. 12-month overlap on breaking changes.
- ULID-prefixed IDs: `dep_`, `spec_`, `req_`, `del_`.
- Customer Data is never trained into foundation models.
  Per-workspace learning only.
- One bearer token per workspace. Revocable.

## Non-goals

- We do not execute code on your behalf.
- We do not orchestrate multi-step workflows. Bring your own runtime.
- We do not expose experts outside the system.
- We do not offer per-seat pricing. Workspace-scoped credits.
- We do not break URL paths between versions.
- We do not serve the open public today.

## Access

Private beta. Three founding-partner slots open.

- Request access: `mailto:api@humandeploy.ai?subject=Deploy API founding partner`
- Partner reference (endpoint-by-endpoint): `https://humandeploy.ai/developers/api/reference/`
- Human-readable overview (this page, as HTML): `https://humandeploy.ai/developers/api/`

## Further reading

- Ship log: `https://humandeploy.ai/developers/`
- Changelog (RSS + JSON feeds): `https://humandeploy.ai/changelog/`
- Status: `https://humandeploy.ai/status`

---

Last updated: 2026-04-23 — HumanDeploy · Covington, KY