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

> Explore the OpenHuman APIs JSON-RPC endpoints in tinyhumansai/openhuman. Access channels, threads, memory, and more with this complete guide.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: api-reference
- Published: 2026-06-11

---

**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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/schemas.rs) file, listing available methods and their type signatures. The [src/core/all.rs](https://github.com/tinyhumansai/openhuman/blob/main/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](https://github.com/tinyhumansai/openhuman/blob/main/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](https://github.com/tinyhumansai/openhuman/blob/main/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](https://github.com/tinyhumansai/openhuman/blob/main/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](https://github.com/tinyhumansai/openhuman/blob/main/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](https://github.com/tinyhumansai/openhuman/blob/main/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](https://github.com/tinyhumansai/openhuman/blob/main/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](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/approval/schemas.rs)).
- **config_*** – Runtime configuration management (logging, autonomy settings) from [src/openhuman/config/schemas.rs](https://github.com/tinyhumansai/openhuman/blob/main/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:

```bash
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:**

```json
{
  "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:

```typescript
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](https://github.com/tinyhumansai/openhuman/blob/main/src/api/socket.rs):

```rust
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](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/channels/controllers/schemas.rs)** – Messaging and channel lifecycle methods.
- **[src/openhuman/composio/schemas.rs](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/composio/schemas.rs)** – External tool integration and OAuth flows.
- **[src/openhuman/threads/schemas.rs](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/threads/schemas.rs)** – Conversation management and turn state.
- **[src/openhuman/embeddings/schemas.rs](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/embeddings/schemas.rs)** – Vector operations and provider config.
- **[src/openhuman/memory/schemas.rs](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/schemas.rs)** – Knowledge base, graph, and document operations.
- **[src/core/all.rs](https://github.com/tinyhumansai/openhuman/blob/main/src/core/all.rs)** – Aggregates all domain schemas into the global registry.
- **[src/api/rest.rs](https://github.com/tinyhumansai/openhuman/blob/main/src/api/rest.rs)** – HTTP server exposing `/rpc`, `/health`, and `/schema` endpoints.
- **[src/api/socket.rs](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/schemas.rs) file (e.g., [src/openhuman/threads/schemas.rs](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/threads/schemas.rs)), which the core aggregates via [src/core/all.rs](https://github.com/tinyhumansai/openhuman/blob/main/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](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/schemas.rs) file that exports its `ControllerSchema`. For example, channel methods are defined in [src/openhuman/channels/controllers/schemas.rs](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/channels/controllers/schemas.rs), while memory operations are in [src/openhuman/memory/schemas.rs](https://github.com/tinyhumansai/openhuman/blob/main/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.