How to Use the OpenHuman API: A Complete JSON-RPC Guide

The OpenHuman API is a JSON-RPC over HTTP interface that runs on a local core server, requiring Bearer token authentication and exposing methods like core.ping, threads_create_new, and agent_chat to manage agents, threads, and tasks programmatically.

The tinyhumansai/openhuman repository provides a Rust-based core that exposes all platform functionality through a JSON-RPC HTTP API. This guide explains how to start the server, authenticate requests, and interact with endpoints using standard HTTP clients or Rust code, based on the actual implementation in src/openhuman/core/jsonrpc.rs and the integration tests in tests/json_rpc_e2e.rs.

Starting the OpenHuman Core Server

The API is served by the openhuman-core binary. To start the JSON-RPC server, build and run the core with the serve command:

# Build the core binary

cargo build --bin openhuman-core

# Start the HTTP JSON-RPC server

./target/debug/openhuman-core serve

When the server starts, it prints a bearer token (stored in <workspace>/core.token) and the local port it is listening on (e.g., 127.0.0.1:7777). All API requests must include this token in the Authorization header.

Authentication and Security

Every request to the OpenHuman API requires authentication via a Bearer token. Include the token generated at startup in your HTTP headers:

Authorization: Bearer <OPENHUMAN_CORE_TOKEN>

The core also respects the OPENHUMAN_APPROVAL_GATE environment variable. When enabled, any destructive operation—such as writes, network calls, or tool installations—requires interactive approval before execution. Background and cron jobs bypass this gate automatically.

JSON-RPC Request Format

The OpenHuman API follows the JSON-RPC 2.0 specification. Each request must be a JSON object containing the standard fields:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "domain_action",
  "params": { ... }
}

• method uses the naming convention domain_action (e.g., core_ping, threads_create_new).
• params is an optional object whose structure depends on the specific method being called.

Core API Methods and Domains

The API is organized into domains, with methods registered in the core HTTP router defined in src/openhuman/core/jsonrpc.rs. Below are the key methods verified by the test suite in tests/json_rpc_e2e.rs:

Core Health and State

• core.ping: Health check that returns { "ok": true }. Demonstrated in tests/json_rpc_e2e.rs at line 1749.
• core.get_state: Retrieves the full persisted state including agents, threads, and todos. Found at line 1761 of the test file.

Thread Management

• threads_create_new: Creates a new chat thread with optional title and labels parameters. Referenced at line 2285.
• threads_update_labels: Updates labels on an existing thread. Referenced at line 2315.

Todo Operations

• todos_add: Adds a new todo item to the user's list. Referenced at line 2396.
• todos_list: Returns all todo items. Referenced at line 2426.
• todos_update_status: Marks a todo as completed or pending. Referenced at line 2444.

Agent and Channel Operations

• agent_chat: Sends a message to an agent and returns a response. Referenced at line 1791.
• channel_web_chat: Sends a chat message to web-based channels like Slack or Discord. Referenced at line 1816.

Registry and Monitoring

• tool_registry_list: Lists all installed tools and Composio adapters. Referenced at line 991.
• agent_registry_create_custom: Registers a new custom agent definition. Referenced at line 1392.
• monitor_list: Lists active background monitors. Referenced at line 1084.

Making API Calls

Using cURL

Send POST requests to the local endpoint with the proper headers and JSON body:

# Ping the core to verify connectivity

curl -X POST http://127.0.0.1:7777 \
  -H "Authorization: Bearer $OPENHUMAN_CORE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"core.ping"}'

# Create a new thread

curl -X POST http://127.0.0.1:7777 \
  -H "Authorization: Bearer $OPENHUMAN_CORE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "id":2,
        "method":"threads_create_new",
        "params":{"title":"My Thread","labels":["demo"]}
      }'

Using Rust

You can interact with the API using the reqwest crate:

use reqwest::blocking::Client;
use serde_json::json;
use std::env;

fn call_rpc(method: &str, params: serde_json::Value) -> serde_json::Value {
    let token = env::var("OPENHUMAN_CORE_TOKEN").expect("Token not set");
    let url = "http://127.0.0.1:7777";  // Replace with actual port
    
    let payload = json!({
        "jsonrpc": "2.0",
        "id": 1,
        "method": method,
        "params": params
    });
    
    Client::new()
        .post(url)
        .bearer_auth(token)
        .json(&payload)
        .send()
        .expect("Request failed")
        .json()
        .expect("Invalid JSON")
}

fn main() {
    // Ping example
    let result = call_rpc("core.ping", json!({}));
    println!("{:#?}", result);
    
    // Create thread example
    let thread = call_rpc(
        "threads_create_new",
        json!({"title": "New Thread", "labels": ["urgent"]})
    );
    println!("{:#?}", thread);
}

Discovering the API Schema

OpenHuman exposes a schema endpoint at GET /schema that returns the complete JSON-RPC method list with parameter specifications. This matches the Rust RpcSchema types defined in the core router.

curl -H "Authorization: Bearer $OPENHUMAN_CORE_TOKEN" \
     http://127.0.0.1:7777/schema | jq .

You can use this endpoint to generate client libraries for other programming languages or to explore available methods dynamically.

Summary

• The OpenHuman API runs as a JSON-RPC HTTP server via the openhuman-core serve command.
• Authentication requires a Bearer token generated at startup and passed in the Authorization header.
• Request format follows JSON-RPC 2.0 with methods named using the domain_action convention.
• Key methods include core.ping, threads_create_new, todos_add, and agent_chat, as implemented in src/openhuman/core/jsonrpc.rs and tested in tests/json_rpc_e2e.rs.
• The /schema endpoint provides discoverable API documentation for building custom clients.

Frequently Asked Questions

What is the endpoint URL for the OpenHuman API?

The OpenHuman API runs on a local HTTP server started by the openhuman-core binary. The URL is http://127.0.0.1:<port> where the port is randomly assigned and displayed when the server starts. You must include the Authorization: Bearer <token> header with every request.

How do I authenticate requests to the OpenHuman API?

All requests require a Bearer token generated when the core starts. The token is printed to stdout and stored in <workspace>/core.token. Include it in your HTTP headers as Authorization: Bearer <token>. The core validates this token for every JSON-RPC request received.

What methods are available in the OpenHuman API?

The API provides methods across multiple domains: core.ping and core.get_state for health and state; threads_create_new and threads_update_labels for thread management; todos_add, todos_list, and todos_update_status for task tracking; and agent_chat, tool_registry_list, and agent_registry_create_custom for agent operations. The full list is available via the GET /schema endpoint.

How do I handle destructive operations in the OpenHuman API?

Set the OPENHUMAN_APPROVAL_GATE environment variable when starting the core. When enabled, destructive commands—such as writes, network calls, or tool installations—require interactive approval before execution. This safety mechanism prevents accidental changes while still allowing programmatic access to read-only and safe operations.

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