OpenHuman APIs: Complete Guide to JSON-RPC Endpoints in tinyhumansai/openhuman

OpenHuman exposes a comprehensive JSON-RPC API organized by domain namespaces (channels, composio, threads, embeddings, memory) where each method follows the openhuman.<namespace>_<function> naming convention and is registered via Rust schema files in the core dispatcher.

The tinyhumansai/openhuman repository implements its public interface through a strongly-typed JSON-RPC layer written in Rust. Each functional domain declares its contract in dedicated schemas.rs files, which the core aggregates into a unified API surface. This architecture enables consistent access to messaging, memory, embedding, and configuration functionality through standard HTTP, WebSocket, or Tauri command interfaces.

API Architecture and Discovery

OpenHuman’s API surface is constructed at compile time from domain-specific schema definitions. Each namespace (e.g., channels, memory) exports a ControllerSchema from its respective schemas.rs file, listing available methods and their type signatures. The src/core/all.rs file aggregates these schemas into the global JSON-RPC dispatcher, which routes incoming requests to the appropriate handlers.

All methods are exposed under the openhuman prefix using the pattern openhuman.<namespace>_<function>. The complete schema definition can be retrieved at runtime by calling the openhuman.schema method, which returns the full registry of available endpoints, input parameters, and output types.

Available API Namespaces

Channels API

The Channels domain manages messaging integrations (Slack, Discord, Telegram). Its methods follow the openhuman.channels_* pattern and are defined in src/openhuman/channels/controllers/schemas.rs.

• channels_describe – Returns metadata for a channel including authentication mode and connection state.
• channels_status – Queries real-time connection health for a specific channel.
• channels_connect – Initiates authentication flows using stored credentials or OAuth.
• channels_disconnect – Terminates connections and optionally clears cached channel memory.
• channels_test – Runs diagnostics to verify channel configuration.
• channels_telegram_login_start / channels_telegram_login_check – Manages Telegram QR-code login flows.
• channels_discord_link_start / channels_discord_link_check – Handles Discord account linking workflows.
• channels_send_message – Dispatches text payloads to a channel.
• channels_send_reaction – Adds emoji reactions to specific messages.
• channels_create_thread – Spawns new conversation threads within a channel.
• channels_update_thread – Modifies thread metadata such as title or labels.
• channels_list_threads – Enumerates all active threads in a channel.

Composio API

The Composio namespace provides external tool integration (Gmail, Notion, etc.) through OAuth and webhook triggers. Definitions reside in src/openhuman/composio/schemas.rs.

• composio_list_toolkits – Lists enabled toolkits and their capabilities.
• composio_list_capabilities – Describes specific actions available within a toolkit.
• composio_authorize – Begins OAuth flows for third-party connections.
• composio_execute – Invokes a tool action (e.g., sending an email).
• composio_create_trigger – Registers webhook triggers for event-driven automation.
• composio_list_triggers – Shows existing trigger registrations.
• composio_enable_trigger / composio_disable_trigger – Toggles trigger activation states.
• composio_set_api_key / composio_clear_api_key – Manages per-toolkit API credentials.

Threads API

The Threads domain handles conversation lifecycle and message history. Method signatures are defined in src/openhuman/threads/schemas.rs.

• threads_list – Returns all conversation threads with pagination.
• threads_upsert – Creates or updates a thread by ID, title, and timestamps.
• threads_create_new – Generates a new thread with an auto-generated identifier.
• threads_messages_list – Retrieves paginated message history for a thread.
• threads_message_append – Adds a new message to a conversation thread.
• threads_generate_title – Requests an AI-generated title for the thread.
• threads_update_labels / threads_update_title – Modifies thread metadata.
• threads_message_update – Edits existing message content.
• threads_turn_state_get / threads_turn_state_list / threads_turn_state_clear – Manages per-turn agent state storage.
• threads_task_board_get / threads_task_board_put – Reads or writes kanban-style task boards attached to threads.

Embeddings API

The Embeddings namespace controls vector-store operations and provider configuration. Schemas are located in src/openhuman/embeddings/schemas.rs.

• embeddings_set_api_key – Stores the API key for the embedding provider (OpenAI, etc.).
• embeddings_clear_api_key – Securely removes stored credentials.
• embeddings_embed – Converts text input into a vector representation.
• embeddings_test_connection – Validates connectivity to the embedding provider.
• embeddings_update_settings – Adjusts provider-specific parameters like model or dimensions.

Memory API

The Memory domain provides the largest API surface, covering persistent knowledge base operations, document ingestion, and graph storage. Definitions are in src/openhuman/memory/schemas.rs.

• memory_init – Initializes the memory subsystem and creates database indexes.
• memory_sync_all – Triggers full synchronization from all external sources (email, Slack, etc.).
• memory_sync_channel – Syncs data from a specific channel only.
• memory_ingestion_status – Returns progress of active ingestion jobs.
• memory_list_files / memory_read_file / memory_write_file – Simple file-like KV storage operations.
• memory_list_namespaces / memory_query_namespace / memory_clear_namespace – Namespace-scoped key-value operations.
• memory_recall_memories – Semantic search across stored memories.
• memory_doc_put / memory_doc_ingest / memory_doc_list / memory_doc_delete – Document CRUD and ingestion pipelines.
• memory_graph_upsert / memory_graph_query – Stores and retrieves graph-structured data.
• memory_tool_rule_put / memory_tool_rule_get / memory_tool_rule_delete / memory_tool_rule_list – Manages agent tool-access rules.
• memory_learn_all – Executes bulk learning passes over stored data.

Core Utilities

Utility endpoints for health checks and system configuration are defined in src/openhuman/health/schemas.rs and adjacent files.

• health – Returns service status (exposed at GET /health and via RPC).
• schema – Returns the complete JSON-RPC schema definition.
• approval_* – Manages approval gates for interactive agent turns (defined in src/openhuman/approval/schemas.rs).
• config_* – Runtime configuration management (logging, autonomy settings) from src/openhuman/config/schemas.rs.

How to Call OpenHuman APIs

All methods accept a JSON-RPC 2.0 envelope and return a standard response object containing either a result or an error field.

Direct HTTP Requests with curl

The core exposes an HTTP endpoint at /rpc (default port 8080) for direct JSON-RPC calls:

curl -X POST http://127.0.0.1:8080/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "demo-1",
    "method": "openhuman.channels_describe",
    "params": {"channel": "slack"}
  }'

Expected response:

{
  "jsonrpc": "2.0",
  "id": "demo-1",
  "result": {
    "channel": "slack",
    "authMode": "OAuth",
    "connected": true
  }
}

Tauri Frontend Integration

The desktop UI communicates with the Rust core via Tauri’s command system using the core_rpc_relay command:

import { invoke } from '@tauri-apps/api/tauri';

async function openhumanRpc(method: string, params: any) {
  const payload = { 
    jsonrpc: '2.0', 
    id: crypto.randomUUID(), 
    method, 
    params 
  };
  const response = await invoke('core_rpc_relay', { request: payload });
  if ('error' in response) throw new Error(response.error.message);
  return response.result;
}

// Example: List all conversation threads
openhumanRpc('openhuman.threads_list', { limit: 10 })
  .then(res => console.log('threads:', res))
  .catch(err => console.error('RPC error:', err));

Rust Socket Client

For native Rust applications, use the WebSocket client provided in src/api/socket.rs:

use openhuman::api::socket::SocketClient;
use serde_json::json;

#[tokio::main]
async fn main() {
    let client = SocketClient::connect("ws://127.0.0.1:8080/socket")
        .await
        .unwrap();

    let resp = client
        .call("openhuman.composio_list_toolkits", json!({}))
        .await
        .unwrap();

    println!("Available toolkits: {:?}", resp);
}

The SocketClient automatically wraps requests in the JSON-RPC envelope and decodes responses using the schema-defined types.

Key Implementation Files

Understanding the source layout helps when extending or debugging the API:

• src/openhuman/channels/controllers/schemas.rs – Messaging and channel lifecycle methods.
• src/openhuman/composio/schemas.rs – External tool integration and OAuth flows.
• src/openhuman/threads/schemas.rs – Conversation management and turn state.
• src/openhuman/embeddings/schemas.rs – Vector operations and provider config.
• src/openhuman/memory/schemas.rs – Knowledge base, graph, and document operations.
• src/core/all.rs – Aggregates all domain schemas into the global registry.
• src/api/rest.rs – HTTP server exposing /rpc, /health, and /schema endpoints.
• src/api/socket.rs – WebSocket transport for the Tauri frontend.

Summary

• OpenHuman uses JSON-RPC 2.0 as its primary API protocol, accessible via HTTP, WebSocket, or Tauri commands.
• APIs are organized by domain namespaces (channels, composio, threads, embeddings, memory) following the openhuman.<namespace>_<function> convention.
• Each domain defines its contract in a schemas.rs file (e.g., src/openhuman/threads/schemas.rs), which the core aggregates via src/core/all.rs.
• The Memory API provides the broadest surface, covering document ingestion, graph storage, and semantic recall.
• TypeSchema definitions ensure compile-time validation of all API inputs and outputs, with runtime schema discovery available via the openhuman.schema method.

Frequently Asked Questions

What protocol does OpenHuman use for its API?

OpenHuman uses JSON-RPC 2.0 over HTTP and WebSocket. The core exposes a /rpc endpoint that accepts standard JSON-RPC requests and returns JSON-RPC responses with either a result or error field. This design allows any language or framework with HTTP capabilities to interact with the system.

How can I discover all available methods programmatically?

Call the openhuman.schema method (defined in src/openhuman/health/schemas.rs). This returns a complete machine-readable registry of all registered methods, their input parameters, and output types. Alternatively, inspect the individual schemas.rs files in each domain directory to see the Rust type definitions.

Where are OpenHuman API schemas defined in the source code?

Each namespace has a dedicated schemas.rs file that exports its ControllerSchema. For example, channel methods are defined in src/openhuman/channels/controllers/schemas.rs, while memory operations are in src/openhuman/memory/schemas.rs. These files declare the method names, parameter types, and handler mappings that the core compiles into the running API server.

Can I use OpenHuman APIs from Python or other languages?

Yes. Since OpenHuman exposes a standard JSON-RPC interface over HTTP, you can use any HTTP client library (Python’s requests, JavaScript’s fetch, etc.) to POST JSON-RPC payloads to the /rpc endpoint. The WebSocket transport at /socket is also language-agnostic, requiring only a WebSocket client that can send and receive JSON text frames.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}