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

> Learn to use the OpenHuman API with this JSON-RPC guide. Discover how to manage agents, threads, and tasks programmatically via HTTP using Bearer token authentication. Explore core methods like ping and agent_chat.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: how-to-guide
- Published: 2026-06-15

---

**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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/core/jsonrpc.rs) and the integration tests in [`tests/json_rpc_e2e.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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:

```bash

# 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:

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

```json
{
  "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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/core/jsonrpc.rs). Below are the key methods verified by the test suite in [`tests/json_rpc_e2e.rs`](https://github.com/tinyhumansai/openhuman/blob/main/tests/json_rpc_e2e.rs):

### Core Health and State

- **`core.ping`**: Health check that returns `{ "ok": true }`. Demonstrated in [`tests/json_rpc_e2e.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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:

```bash

# 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:

```rust
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.

```bash
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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/core/jsonrpc.rs) and tested in [`tests/json_rpc_e2e.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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.