http.md

HTTP API

The HTTP API is mounted under /api/v1. Protected endpoints use Authorization: Bearer <jwt>. Chat, Memory, and Usage routes also accept the configured X-API-Key; Runtime administration and durable execution routes require a Bearer token.

The OpenAPI 3.1 route inventory is generated from the mounted Express routers and is available at GET /openapi.json and GET /docs/openapi.json. The HTML /docs page and /docs/json response are retained as legacy human-readable indexes. This document remains the field-level behavioral contract; release CI checks the machine-readable inventory so newly mounted routes cannot silently disappear from API discovery.

Responses use a common envelope:

{
  "success": true,
  "data": {},
  "message": "optional"
}

Errors use:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message"
  }
}

Health

GET /health

Returns process health.

Field	Type	Description
status	string	Current health status.
timestamp	string	ISO timestamp generated by the server.
uptime	number	Node.js process uptime in seconds.

Authentication

Method	Path	Auth	Description
POST	/auth/login	none	Login with email and password.
POST	/auth/register	none	Register a user when registration is enabled.
GET	/auth/me	JWT	Read the current account.
PUT	/auth/me	JWT	Update display name and preferences.
POST	/auth/api-key	JWT	Create an API key.
GET	/auth/api-keys	JWT	List API keys.
DELETE	/auth/api-key/:keyId	JWT	Delete an API key.
POST	/auth/refresh	JWT	Refresh a JWT.

POST /auth/login request:

{
  "email": "owner@example.com",
  "password": "password"
}

POST /auth/api-key request:

{
  "name": "local-client",
  "permissions": ["chat:read", "chat:write"]
}

Chat

Method	Path	Description
POST	/chat	Send a non-streaming chat message.
POST	/chat/stream	Stream a chat response over SSE.
GET	/chat/:sessionId	Read chat history.
POST	/chat/:sessionId/clear	Clear temporary session history.
DELETE	/chat/:sessionId	Delete a chat session.

POST /chat request:

{
  "sessionId": "sess_abc123",
  "message": "Summarize the active workflow",
  "model": "default",
  "provider": "openai",
  "agentId": "default",
  "cache": {
    "kvCache": true,
    "writeKvCache": { "mode": "write_if_missing", "ttlMs": 3600000 }
  }
}

Field	Required	Description
sessionId	no	Existing session id. A new id is generated when omitted.
message	yes	Non-empty user message.
model	no	Model alias or provider model name.
provider	no	Provider id.
agentId	no	Agent profile id.
cache	no	true enables session-scoped KV cache read/write. An object may define prefix, kvCache, and writeKvCache; KV refs are normalized per user, session, provider, and model.

Chat responses include sessionId, runId, messageId, content, model, provider, finishReason, usage, and optional toolCalls.

SSE done events from POST /chat/stream include type, content, sessionId, runId, resolved model, resolved provider, and optional usage.

Memory

Method	Path	Description
GET	/memory/temp	List temporary sessions for the current user.
GET	/memory/temp/:sessionId	Read temporary memory for a session.
DELETE	/memory/temp/:sessionId	Clear temporary memory.
GET	/memory/permanent	List permanent conversations.
POST	/memory/permanent	Create a permanent conversation.
GET	/memory/permanent/:id	Read a permanent conversation.
GET	/memory/permanent/:id/messages	Read conversation messages.

Temporary memory is session-scoped. Permanent memory is user-scoped and supports pagination filters such as page, pageSize, agentId, isArchived, startDate, and endDate.

Runtime Resources

Route Group	Description
/models	List and inspect configured LLM providers and model aliases.
/tools	List available tools and their schemas.
/skills	List and administer skill definitions.
/workflows	Inspect workflow definitions and runtime workflow status.
/runtime	Read run projections, events, replay, audit, and regression views.
/status	Read service, provider, and dependency status.
/usage	Read token and usage metrics for the current user.
/docs	Render the built-in route index.

Models

Method	Path	Description
GET	/models	List configured models. Optional provider query filters by provider id.
GET	/models/health	Return provider health, default provider, and default model.
GET	/models/:id	Return one model by id.
GET	/models/providers/list	List configured providers and default marker.
POST	/models/switch	Switch default provider and/or model for the running server.
GET	/models/defaults/current	Return the current default provider and model.

POST /models/switch request:

{
  "provider": "openai",
  "model": "default-reasoning"
}

Tools

Method	Path	Description
GET	/tools	List registered tools.
GET	/tools/:id	Read one normalized Tool descriptor.
POST	/tools/execute	Execute a tool through the governed runtime path.
GET	/tools/mcp/servers	List MCP servers through the compatibility route.
GET	/tools/mcp/servers/:id/health	Read one MCP server health record.
POST	/tools/mcp/servers/:id/connect	Connect an MCP server. Admin only.
POST	/tools/mcp/servers/:id/disconnect	Disconnect an MCP server. Admin only.
GET	/tools/mcp/tools	List normalized tools from connected MCP servers.

POST /tools/execute request:

{
  "name": "search",
  "params": { "query": "hypha" },
  "sessionId": "sess_abc123"
}

Tool execution returns top-level runId, invocationId, and data. A Tool that requires human approval returns HTTP 202; use its invocationId with the approval routes below.

MCP tools use the same endpoint. Connected MCP tools are listed with stable fully qualified names such as filesystem.read_file:

{
  "name": "filesystem.read_file",
  "params": { "path": "/README.md" },
  "sessionId": "sess_abc123"
}

The default config.yaml starts the real local stdio MCP example:

tools:
  mcpServers:
    - id: 'local-example'
      name: 'Hypha Local MCP Example'
      mode: 'local'
      command: 'node'
      args: ['./examples/mcp/local-stdio-server.cjs']
      autoConnect: true
      required: true

Deployment MCP servers use the same list with mode: "local" and command/args, or mode: "remote" and endpoint plus optional credentialRef. Fixture mode is test-only and is rejected in production. GET /tools/mcp/tools reports normalized ToolSpec records, including sourceRef.serverId and sourceRef.capabilityId.

The built-in search tool uses real HTTP providers in production. Set WEB_SEARCH_PROVIDER=auto to try duckduckgo,wikipedia in order, WEB_SEARCH_PROVIDER=china to prefer mainland China providers baidu,so360, WEB_SEARCH_PROVIDER=baidu or so360 for explicit mainland no-key suggest providers, WEB_SEARCH_PROVIDER=wikipedia for Wikipedia OpenSearch, or WEB_SEARCH_PROVIDER=duckduckgo for a DuckDuckGo Instant Answer-compatible endpoint while keeping the same POST /tools/execute contract. Request params may include provider and fallbackProviders for per-call overrides. The deterministic stub is limited to tests and non-production development and is rejected by production lifecycle and calls.

Tools that require human approval return HTTP 202 with data.status set to human_review_required. The run remains queryable through /runtime/runs/:runId and projects as waiting_human from run.waiting_human events.

Invocation and Approval Operations

Method	Path	Description
GET	/tool-invocations/:id	Read an Invocation owned by the current user; admins may read any.
POST	/tool-invocations/:id/cancel	Cancel an owned Invocation.
POST	/tool-approvals/:id/approve	Approve and resume a waiting Invocation. Admin only.
POST	/tool-approvals/:id/reject	Reject a waiting Invocation and fail its active Run. Admin only.

Approval completion projects ObservationRecorded, Verifying, MemorySync, and run.completed events. Rejection projects the Run to Failed and records run.failed.

MCP Catalog and Context Operations

Method	Path	Description
GET	/mcp/servers	List configured MCP connection records.
POST	/mcp/servers/:id/connect	Connect a configured MCP server. Admin only.
POST	/mcp/servers/:id/disconnect	Disconnect a configured MCP server. Admin only.
GET	/mcp/capabilities	List normalized Tool, Resource, and Prompt capability revisions.
GET	/mcp/drifts	List detected capability drift records.
POST	/mcp/servers/:serverId/capabilities/:capabilityId/approve	Approve an exact capability hash. Admin only.
POST	/mcp/servers/:serverId/capabilities/:capabilityId/quarantine	Quarantine an exact capability revision. Admin only.
GET	/mcp/servers/:serverId/resources	List approved Resources.
POST	/mcp/servers/:serverId/resources/read	Read an approved Resource through a scoped, event-backed Runtime Run.
GET	/mcp/servers/:serverId/prompts	List approved Prompts.
POST	/mcp/servers/:serverId/prompts/:name/render	Render an approved Prompt through a scoped, event-backed Runtime Run.

Approvals are revision-specific and require capabilityHash. A Tool whose server descriptor does not declare its side-effect level remains conservatively classified until an administrator supplies sideEffectLevel; this explicit classification cannot downgrade a server-declared level. Resource and Prompt results include runId, and their authorization, capability snapshot, call lifecycle, and terminal status are recorded under that canonical Run.

Workflows

Method	Path	Description
GET	/workflows	List workflow definitions.
GET	/workflows/:name	Read a workflow definition.
POST	/workflows/:name/execute	Execute a workflow and return its runtime runId.
POST	/workflows	Load a workflow definition. Admin only.
DELETE	/workflows/:name	Unload a workflow definition. Admin only.
GET	/workflows/executions/:executionId	Read workflow execution status.
POST	/workflows/executions/:executionId/cancel	Cancel a running workflow execution.

POST /workflows/:name/execute request:

{
  "context": {
    "sessionId": "sess_abc123",
    "messages": [{ "role": "user", "content": "Run this workflow" }],
    "variables": {},
    "metadata": {}
  },
  "version": "1.0.0"
}

Workflow execution creates a runtime run, records workflow stage events, and returns an execution object plus runId when available.

Skills

Method	Path	Description
GET	/skills	List available skills.
GET	/skills/:id	Read one skill.
GET	/skills/installed	List installed skill files.
POST	/skills/install	Install a Markdown skill from inline content.
DELETE	/skills/install/:id	Uninstall a skill. Admin only.
POST	/skills/reload	Reload skill definitions.
PATCH	/skills/:id	Update skill metadata or activation state. Admin only.

POST /skills/install request:

{
  "source": "inline",
  "content": "---\nname: Example\nversion: 0.0.0\ndescription: Example skill\npriority: 10\n---\nSkill instructions."
}

source is required and must be inline, path, or url; provide the matching content, path, or url field. Optional integrity, signature, manifest, filename, and activation fields are accepted for controlled installation.

Runtime Projections

Runtime views are derived from events recorded during a run.

Method	Path	Description
GET	/runtime/runs/:runId	Project run state from events.
GET	/runtime/runs/:runId/events	List source events for a run.
GET	/runtime/runs/:runId/fsm	Inspect process identity, revision, current State, and allowed transitions.
GET	/runtime/runs/:runId/replay	Return replay state path and event-derived call details.
GET	/runtime/runs/:runId/audit	Return audit counters and policy evidence.
GET	/runtime/runs/:runId/regression	Return event-type, state-path, tool, memory, and output regression inputs.

Replay responses include runId, events, statePath, toolCallEventIds, policyDecisionEventIds, memoryEventIds, modelCalls, terminal toolCalls, memoryReads, memoryWrites, policyDecisions, and optional finalOutput.

Audit responses include eventCount, policyDecisionCount, memoryWriteCount, toolCallCount, and missingRunIds.

Regression responses include eventTypes, statePath, toolCalls, memoryWriteCount, and optional finalOutput.

Durable Session Commands

POST /runtime/sessions/:sessionId/commands/start-run is the durable Agent execution entry point. It requires a unique Idempotency-Key header and returns HTTP 202 with the persisted command.

{
  "input": { "question": "What is Hypha?" },
  "agentId": "agent.release-research",
  "workflowRef": { "id": "workflow.research", "version": "1.0.0" },
  "domainPack": {},
  "react": {
    "modelAlias": "default-chat",
    "agentSpec": {},
    "messages": [{ "role": "user", "content": "What is Hypha?" }],
    "budget": { "iterations": 8, "modelCalls": 8, "toolCalls": 4 }
  },
  "metadata": { "source": "release-consumer" }
}

The top-level request is strict. react.messages requires at least one bounded system, user, or assistant message. Optional budgets and deadlineAt are validated before the command is queued. Poll GET /runtime/sessions/:sessionId/commands; optional status, fromSequence, and limit filters support restart-safe consumers.

Custom FSM Runs submit a complete validated fsm without react, or submit a DomainPack workflow that the Server compiles. ReAct Runs always retain the framework-owned Harness FSM. See Custom FSM Topologies.

Governed FSM Control

Method	Path	Description
GET	/runtime/runs/:runId/fsm	Return the Event-derived FSM view and current Run revision.
POST	/runtime/runs/:runId/fsm/transitions	Apply one declared edge with owner, revision, guard, and Lease evidence.

Manual transitions require Idempotency-Key plus processId, processVersion, expectedState, expectedRunRevision, targetState, and reason. Optional guardContext supplies deterministic input, variables, and metadata for a declared guard. The endpoint cannot add a node, invent an edge, bypass Policy/HumanTask approval, or leave a terminal Run.

Agent Prompts and Human Tasks

Method	Path	Description
GET	/runtime/agent-prompts	List registered versioned Agent Prompts.
POST	/runtime/agent-prompts	Register a validated Prompt. Admin only.
PUT	/runtime/agent-prompts/:id/:version	Replace a Prompt using numeric If-Match revision evidence. Admin only.
DELETE	/runtime/agent-prompts/:id	Remove an optional exact version. Admin only.
GET	/runtime/reasoning/strategies	List available reasoning strategies.
GET	/runtime/runs/:runId/human-tasks	List HumanTasks owned by the Run user.
POST	/runtime/runs/:runId/human-tasks/:taskId/decision	Approve or reject the exact task subject and revision.

HumanTask decisions require Idempotency-Key and a body containing decision, positive expectedRevision, exact expectedSubjectHash, and optional reason. The Runtime revalidates the subject after approval rather than treating an old approval as open-ended authority.

Concurrency

Chat requests are queued per userId + sessionId. Requests for the same user's session are serialized, while different users and different sessions can run independently.

Usage and Status

Method	Path	Description
GET	/usage/stats	Aggregate token and cost statistics.
GET	/usage/recent	Recent usage records.
GET	/usage/conversation/:conversationId	Usage records for one conversation.
GET	/usage/pricing	Current pricing table used for estimates.
GET	/usage/page	Paginated usage records.
GET	/status	JSON service/provider/dependency status.
GET	/status/page	Human-readable status page.