Aleph
API Reference

JSON-RPC API

Complete method reference for the WebSocket JSON-RPC 2.0 interface

This page is a compact quick-reference for every JSON-RPC method exposed by the Aleph Gateway. For detailed request/response examples, follow the links to the individual method pages.

Transport

All methods are invoked over a WebSocket connection to the Gateway server (default ws://127.0.0.1:18790). The protocol is JSON-RPC 2.0 -- every request requires jsonrpc, method, and id fields. Notifications (no id) are used for server-to-client events.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "agent.run",
  "params": { "message": "Hello" }
}

Authentication

When require_auth is enabled in the Gateway config, the first message on a new WebSocket connection must be connect. All subsequent requests are rejected until authentication succeeds.

MethodDescriptionParameters
connectAuthenticate a WebSocket connectiontoken (string), client_id (string, optional)

Method Index

agent.* -- Agent Execution

Full documentation

MethodDescriptionKey ParametersReturns
agent.runStart an agent run with streamingmessage, session_key?, thinking?, model?{ run_id, status, session_key }
agent.cancelCancel a running agentrun_id{ cancelled, run_id }
agent.statusGet run status (polling)run_id{ run_id, status, iterations, tokens_used }
agent.listList available agent configurations--{ agents[] }
agent.respondToInputSend follow-up input to a waiting runrun_id, message{ queued }

session.* -- Session Management

Full documentation

MethodDescriptionKey ParametersReturns
session.listList sessions with filtersfilter?, limit?, offset?{ sessions[], total }
session.historyGet raw message historysession_key, limit?{ messages[], token_count }
session.compactTrigger manual compactionsession_key{ tokens_before, tokens_after, facts_extracted }
session.deletePermanently delete a sessionsession_key{ deleted, messages_removed }

config.* -- Configuration

Full documentation

MethodDescriptionKey ParametersReturns
config.getGet active configuration--{ config, source, loaded_at }
config.reloadReload from disk--{ reloaded, changed_keys }
config.validateValidate without applyingconfig{ valid, errors[], warnings[] }
config.schemaGet configuration JSON Schema--JSON Schema object

exec.* -- Command Execution Security

Full documentation

MethodDescriptionKey ParametersReturns
exec.approval.requestRequest command approvalcommand, cwd, agent_id, timeout_ms?{ id, approved, decision }
exec.approval.resolveResolve a pending approvalid, decision, resolved_by?{ resolved }
exec.approvals.getGet approval configuration--{ config, hash }
exec.approvals.setUpdate approval configconfig, base_hash{ applied }
exec.approvals.pendingList pending approvals--{ pending[] }

events.* -- Event Subscriptions

Full documentation

MethodDescriptionKey ParametersReturns
events.subscribeSubscribe to event topicspatterns[]{ subscribed[], active_patterns[] }
events.unsubscribeRemove subscriptionspatterns[]{ unsubscribed[], active_patterns[] }
events.listList active subscriptions--{ patterns[], total }

wizard.* -- Setup Wizards

Full documentation

MethodDescriptionKey ParametersReturns
wizard.startStart a wizard sessionwizard_type, initial_data?{ session_id, step, status }
wizard.answerAnswer current stepsession_id, step_id, value{ done, step?, status }
wizard.nextAdvance past informational stepsession_id{ done, step?, status }
wizard.cancelCancel a wizardsession_id{ cancelled }
wizard.statusGet wizard statussession_id{ status }

cron.* -- Scheduled Jobs

Full documentation

MethodDescriptionKey ParametersReturns
cron.createCreate a scheduled jobname, schedule, agent_id, prompt{ job_id, next_run_at }
cron.listList all jobsfilter?{ jobs[], total }
cron.getGet job details + run historyjob_idJob object with recent_runs[]
cron.deleteDelete a jobjob_id{ deleted }
cron.triggerManually trigger a jobjob_id{ triggered, run_id }
cron.pausePause a jobjob_id{ paused }
cron.resumeResume a paused jobjob_id{ resumed, next_run_at }
cron.statusGet scheduler status--Scheduler state

browser.* -- Browser Automation

Full documentation

MethodDescriptionKey ParametersReturns
browser.navigateNavigate to a URLurl, wait_until?, timeout_ms?{ url, title, status }
browser.clickClick an elementtarget (ActionTarget){ clicked }
browser.typeType text into an elementtarget, text, clear?{ typed }
browser.screenshotCapture a screenshottarget?, full_page?, format?{ data_base64, width, height }
browser.evaluateExecute JavaScriptscript, timeout_ms?{ value, type }
browser.snapshotTake ARIA accessibility snapshot--{ elements[], page_title }

chat.* -- Chat Control

MethodDescriptionKey ParametersReturns
chat.sendSend a chat messagemessage, session_key?Run info
chat.abortAbort current chat generationrun_id?{ aborted }
chat.historyGet chat historysession_key?, limit?{ messages[] }
chat.clearClear chat historysession_key?{ cleared }

models.* -- Model Discovery

MethodDescriptionKey ParametersReturns
models.listList available models--{ models[] }
models.getGet model detailsmodel_idModel metadata
models.capabilitiesGet model capabilitiesmodel_idCapability flags

memory.* -- Memory Operations

MethodDescriptionKey ParametersReturns
memory.searchSearch stored memoriesquery, limit?{ results[] }

skills.* -- Skills Management

MethodDescriptionKey ParametersReturns
skills.listList installed skills--{ skills[] }
skills.installInstall a skillname, sourceInstall result

plugins.* -- Plugin Lifecycle

MethodDescriptionKey ParametersReturns
plugins.listList installed plugins--{ plugins[] }
plugins.loadLoad a plugin into runtimepath{ loaded }
plugins.unloadUnload a pluginplugin_id{ unloaded }
plugins.enableEnable a pluginplugin_id{ enabled }
plugins.disableDisable a pluginplugin_id{ disabled }
plugins.statusGet plugin statusplugin_idPlugin status

services.* -- Background Services

MethodDescriptionKey ParametersReturns
services.listList background services--{ services[] }
services.startStart a servicename{ started }
services.stopStop a servicename{ stopped }
services.statusGet service statusname{ status }

mcp.* -- MCP Approval

MethodDescriptionKey ParametersReturns
mcp.list_pending_approvalsList pending MCP approvals--{ approvals[] }
mcp.respond_approvalRespond to an MCP approvalid, approved{ responded }
mcp.cancel_approvalCancel an MCP approvalid{ cancelled }

markdown_skills.* -- Markdown Skill Runtime

MethodDescriptionKey ParametersReturns
markdown_skills.loadLoad a markdown skillpath{ loaded }
markdown_skills.reloadReload a skillname{ reloaded }
markdown_skills.listList loaded skills--{ skills[] }
markdown_skills.unloadUnload a skillname{ unloaded }

poe.* -- Principle-Operation-Evaluation

MethodDescriptionKey ParametersReturns
poe.runRun a POE taskspec, agent_id?{ run_id }
poe.statusGet POE run statusrun_id{ status, progress }
poe.cancelCancel a POE runrun_id{ cancelled }
poe.listList POE runs--{ runs[] }
poe.preparePrepare a POE contractspec{ contract_id, terms }
poe.signSign a POE contractcontract_id{ signed }
poe.rejectReject a POE contractcontract_id{ rejected }
poe.pendingList pending contracts--{ contracts[] }

identity.* -- Identity/Soul Management

MethodDescriptionKey ParametersReturns
identity.getGet current identity--Identity object
identity.setSet identity fieldsfields{ updated }
identity.clearReset to default identity--{ cleared }
identity.listList available identities--{ identities[] }

workspace.* -- Workspace Isolation

MethodDescriptionKey ParametersReturns
workspace.createCreate a workspacename, config?{ workspace_id }
workspace.listList workspaces--{ workspaces[] }
workspace.getGet workspace detailsworkspace_idWorkspace object
workspace.updateUpdate workspace configworkspace_id, config{ updated }
workspace.archiveArchive a workspaceworkspace_id{ archived }

guests.* -- Guest Invitations

MethodDescriptionKey ParametersReturns
guests.createInvitationCreate a guest invitationpermissions, expires?{ invitation_id, token }
guests.listPendingList pending invitations--{ invitations[] }
guests.revokeInvitationRevoke an invitationinvitation_id{ revoked }

Utility Methods

MethodDescriptionKey ParametersReturns
healthHealth check--{ status: "ok" }
echoEcho back paramsanyEchoed params
versionGet server version--{ version, build }
logs.levelsGet current log levels for all components--{ levels }
logs.set_levelSet log level for a componentcomponent, level{ set }
logs.tailStream recent log entrieslines?, follow?{ entries[] }
commands.listList all registered commands--{ commands[] }

Error Codes

Standard JSON-RPC 2.0 error codes plus Aleph extensions:

CodeConstantDescription
-32700PARSE_ERRORInvalid JSON
-32600INVALID_REQUESTMalformed JSON-RPC request
-32601METHOD_NOT_FOUNDMethod does not exist
-32602INVALID_PARAMSInvalid method parameters
-32603INTERNAL_ERRORInternal server error
-32000AUTH_REQUIREDAuthentication required (send connect first)
-32001AUTH_FAILEDAuthentication credentials rejected
-32002PERMISSION_DENIEDInsufficient permissions
-32003RATE_LIMITEDToo many requests
-32004RESOURCE_NOT_FOUNDRequested resource not found
-32005TIMEOUT_ERROROperation timed out
-32006TOOL_ERRORTool execution failed

Error response format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found: agent.nonexistent"
  }
}

Event Topics

Events are delivered as JSON-RPC notifications (no id field) to subscribed clients. Subscribe via events.subscribe.

Topic PatternDescription
stream.startAgent response streaming begins
stream.chunkText chunk from agent
stream.tool_startTool invocation started
stream.tool_endTool execution completed
stream.thinkingReasoning step (CoT)
stream.endStreaming finished
agent.startedAgent run started
agent.completedAgent run finished
agent.errorAgent run failed
agent.cancelledAgent run cancelled
session.createdNew session created
session.deletedSession deleted
session.compactedSession compacted
config.changedConfiguration modified
config.reloadedConfig reloaded from file
cron.triggeredCron job triggered
cron.completedCron job completed
cron.failedCron job failed
exec.approval_requestedApproval needed for command
exec.approval_resolvedApproval decision made

See Also

  • Rust API -- Core crate reference for library usage
  • Gateway Overview -- Architecture and connection details
  • Protocol -- Transport format and authentication flow

Rust API

Core crate reference for embedding Aleph as a library

Terminology

Standardized terminology and translations for Aleph concepts

On this page

TransportAuthenticationMethod Indexagent.* -- Agent Executionsession.* -- Session Managementconfig.* -- Configurationexec.* -- Command Execution Securityevents.* -- Event Subscriptionswizard.* -- Setup Wizardscron.* -- Scheduled Jobsbrowser.* -- Browser Automationchat.* -- Chat Controlmodels.* -- Model Discoverymemory.* -- Memory Operationsskills.* -- Skills Managementplugins.* -- Plugin Lifecycleservices.* -- Background Servicesmcp.* -- MCP Approvalmarkdown_skills.* -- Markdown Skill Runtimepoe.* -- Principle-Operation-Evaluationidentity.* -- Identity/Soul Managementworkspace.* -- Workspace Isolationguests.* -- Guest InvitationsUtility MethodsError CodesEvent TopicsSee Also