Gateway RPC Methods Reference Methods Reference Overview of all Gateway RPC method namespaces
The Aleph Gateway exposes its functionality through namespaced JSON-RPC 2.0 methods. Each namespace groups related operations, and every method follows the same request/response conventions. The namespace registry lives in src/gateway/handlers/mod.rssrc/bin/aleph-server/commands/start/builder/handlers/ on the boot path.
All RPC requests use the JSON-RPC 2.0 envelope:
{ "jsonrpc" : "2.0" , "id" : "unique-id" , "method" : "namespace.method" , "params" : { ... } }
id can be a string, number, or null (null for notifications)method follows the namespace.action naming conventionparams is an optional JSON object specific to each method
Success:
{ "jsonrpc" : "2.0" , "id" : "unique-id" , "result" : { ... } } Error:
{ "jsonrpc" : "2.0" , "id" : "unique-id" , "error" : { "code" : -32601 , "message" : "Method not found" , "data" : null } } Code Name Description -32700 Parse error Malformed JSON -32600 Invalid Request Missing required fields -32601 Method not found Unknown method name -32602 Invalid params Bad or missing parameters -32603 Internal error Server-side failure -32000 Auth required No credentials provided -32001 Auth failed Invalid token or signature -32002 Permission denied Insufficient permissions -32003 Rate limited Too many requests -32004 Resource not found Requested entity does not exist -32005 Timeout Operation timed out -32006 Tool error Tool execution failed
The table below groups namespaces by topic. Per-method signatures and examples live on each sub-page.
Namespace Methods Description agent.*run / status / cancel / listAgent execution control (see agent.* ) chat.*send / abort / history / clear / rewind / context_estimateChat interface (chat.send shares the execution adapter with agent.run) run.*(stream.* events under events.*) Run-lifecycle events (run.accepted, ...)
Namespace Methods Description config.*schema / get / patch / reload / path / validate / get_full_config / reload_with_subsystems / get_tool_permissions / update_tool_permissionsRuntime config (see config.* ) behavior_config.*get / updateAgent behaviour settings browser_config.*get / updateBrowser automation settings execution_config.*get / updateExecution settings fetch_config.*get / update / testWeb fetch settings general_config.*get / updateGeneral settings generation_config.*get / updateGeneration settings memory_config.*get / updateMemory system settings rerank_config.*get / update / testReranker configuration route_config.*get / updateRouting settings routing_rules.*list / get / create / update / delete / moveTask routing rules search_config.*get / update / test / deleteBackendSearch backend configuration security_config.*get / update / list_devices / revoke_deviceSecurity settings
Namespace Methods Description identity.*get / set / clear / listIdentity / soul file management (see identity.* )
Namespace Methods Description cron.*list / get / create / update / delete / status / run / runs / toggleScheduled jobs (see cron.* ) heartbeat.*list / get / create / update / delete / toggle / wake / runsHeartbeat probe tasks services.*start / stop / list / statusBackground services (see services.* ) daemon.*status / shutdown / logsGateway daemon control (see daemon.* ) logs.*getLevel / setLevel / getDirectoryLog management (see logs.* )
Namespace Methods Description events.*subscribe / unsubscribe / listTopic subscriptions (see events.* ) event(notification) Delivered event frame {topic, data, timestamp} trace.*list / get / by_runsTrace replay (requires state.db; otherwise SERVICE_UNAVAILABLE) activity.*statsActivity statistics
Namespace Methods Description memory.*search / delete / clear / listFacts / clearFacts / stats / compress / reembed / reembed.cancel / retrieve_with_trace / appList / list_corrections / traceMemory system graph.*query / node_detail / search / update_note / rename_note / delete_noteKnowledge graph
Namespace Methods Description agents.*list / get / create / update / delete / set_default / files.list / files.get / files.set / files.delete / tools_schema / teams / bindingsAgent CRUD and file management tools.*catalog / effective / invoke / cancel_call / in_flightTool visibility and invocation commands.*list / executeCommand discovery and execution
Namespace Methods Description skills.*status / update / install_dep / remove / installSkill management bundled.sync— Bundled-skill sync plugin.*list / install / installFromZip / uninstall / update / enable / disable / load / unload / reload / callTool / executeCommandPlugin lifecycle (canonical namespace) plugins.*list / install / installFromZip / uninstall / enable / disable / load / unload / callTool / executeCommandPlugin lifecycle (legacy namespace, kept for compatibility) plugin.marketplace.*list / add / update / remove / installPlugin marketplace extensions.*catalog / installed / toggle / uninstall / disclosure / configure / installUnified Extensions Store facade
Namespace Methods Description providers.*list / get / create / update / delete / setDefault / test / needsSetup / healthcheck / modelsRefresh / catalog / oauthLogin / oauthLogout / oauthStatusAI provider management generation_providers.*list / get / create / update / delete / setDefault / test / voices / list_presetsMedia generation providers embedding_providers.*list / get / add / update / remove / setActive / test / presetsEmbedding providers
Namespace Methods Description mcp.*list_pending_approvals / respond_approval / cancel_approvalMCP approval handling mcp_config.*list / get / create / update / delete / migrate_unified_to_actorMCP server configuration acp.*list / get / create / update / delete / test / set_enabled / presets / presets_meta / sessions.list / sessions.cancel / sessions.shutdownACP harness configuration
Namespace Methods Description channel.*start / stop / pairing_data / send / create / delete / list / status / health / dead_letters / redrive_dead_lettersPer-channel operations channels.*list / status / set_agentChannel listing and status sessions.*list / history / reset / delete / new / set_topic / patch / preview / compaction.list / compaction.restore / compaction.branchSession lifecycle (plural namespace) session.*usage / compact / truncateSession operations (singular namespace, partially requires SessionStore)
Namespace Methods Description teams.*create / get / list / rename / disband / delete / chat.send / chat.cancel / chat.thread / chat.history / create_task / update_task / list_tasks / task.trace / snapshot.* / workflow.* / acp_member.* / usageTeam management group_chat.*start / continue / mention / end / list / historyMulti-agent group chat subagent.tree— Subagent tree snapshot a2a_delegate / a2a_*— A2A subagent tools
Namespace Methods Description runtimes.*list / refresh / installRuntime capability management workspace.*create / list / get / update / archiveWorkspace isolation projects.*list / add / create_blank / remove / touch / getProject catalogue agents.bindings— agent ↔ channel bindings
Namespace Methods Description wizard.*start / next / answer / cancel / statusMulti-step configuration wizard (no corresponding CLI subcommand) hooks.*list / registry / add / remove / reload / events~/.aleph/hooks.json admin
Namespace Methods Description health— Health check echo— Echo test version— Server version system.info— System metrics (CPU, memory, disk, uptime) request.state— Per-request state read/write gateway.identity.get— Gateway-side instance identity gateway.metrics.lanes— LaneManager semaphore gauges gateway.metrics.run_concurrency— AgentRunManager concurrency gauges gateway.credentials— Gateway credential info gateway.ticket.* / gateway.token.* / gateway.devices.*— Pairing and credential admin pty.*spawn / input / resize / close / listEmbedded interactive terminal
Namespace Methods Description auth.* / pairing.* / devices.*connect / approve / reject / list / revoke / show_token / reset_token / list_sessions / revoke_sessionAuthentication and device management secrets.*list / set / delete / verify / providersVault management exec_approvals.*request / resolve / pendingExec approval clarification.*resolve / pendingask_user clarificationfs.*home_dir / list_dir / create_dir / read_file / allowed_rootsSandboxed fs operations insights.tools— Memory tool introspection (requires MemoryBackend) dreaming.run_now— Eager-trigger dreaming
HandlerRegistry::new() in src/gateway/handlers/mod.rs pre-registers a set of methods so METHOD_NOT_FOUND is deterministic:
Ready immediately — health / echo / version / system.info / request.state / config.schema / logs.getLevel / logs.setLevel / logs.getDirectory / services.* / pty.* / plugins.* / plugin.* / hooks.* / mcp.list_pending_approvals / mcp.respond_approval / mcp.cancel_approval / skills.* / bundled.sync / daemon.logsStub until boot overrides — cron.* / heartbeat.* / chat.send / chat.abort / chat.history / chat.clear / session.usage / session.compact / session.truncate / workspace.* / channels.set_agent / agents.bindings / groups_* / daemon.status / daemon.shutdown / teams.* / agents.* / runtimes.* / tools.* / insights.tools / gateway.identity.get / gateway.metrics.* / gateway.credentials / trace.* / wizard.*Not registered (METHOD_NOT_FOUND until injected) — identity.get / identity.set / identity.clear / identity.list (must go through register_identity_handlers); graph.* (must go through register_graph_handlers)
Stubs are overridden by the corresponding register_*_handlers call on the boot path (src/bin/aleph-server/commands/start/builder/handlers/) before the first request is served.
Methods that return lists accept optional limit / offset (exact semantics vary per method; see each sub-page):
{ "jsonrpc" : "2.0" , "id" : 1 , "method" : "cron.list" , "params" : { "limit" : 20 , "offset" : 0 } } agent.run and chat.send emit events on the stream.* and agent.* topics. Subscribe first:
{ "jsonrpc" : "2.0" , "id" : 1 , "method" : "events.subscribe" , "params" : { "topics" : [ "agent.*" ] } } { "jsonrpc" : "2.0" , "id" : 2 , "method" : "agent.run" , "params" : { "input" : "Hello" } } { "jsonrpc" : "2.0" , "method" : "event" , "params" : { "topic" : "agent.response.chunk" , "data" : { "content" : "Hi!" } } } See events.* .