http.md

HTTP API

The HTTP API is mounted under /api/v1. Protected endpoints currently require Authorization: Bearer <jwt>. API key records can be managed through the authentication routes, but X-API-Key request authentication is not enabled by the default Express middleware.

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 registers a local fixture gateway:

tools:
  mcpServers:
    - id: 'classic'
      name: 'Classic MCP Fixture'
      mode: 'fixture'
      autoConnect: true

Deployment MCP servers use the same list with mode: "local" and command/args, or mode: "remote" and endpoint plus optional authToken. GET /tools/mcp/tools reports normalized ToolSpec records, including sourceRef.serverId and sourceRef.capabilityId.

The built-in search tool uses deterministic offline results by default. Set WEB_SEARCH_PROVIDER=auto to try duckduckgo,wikipedia,stub in order, WEB_SEARCH_PROVIDER=china to prefer mainland China providers baidu,so360,stub, 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.

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 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 capability catalog records.
GET	/mcp/drifts	List detected capability drift records.

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:

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

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/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.

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.