Skip to main content
The Heurist Mesh REST API enables interaction with AI agents and tools through HTTP endpoints. This API is part of the open source Heurist Agent Framework. Contributions are highly encouraged!

​
Quick Start

// Example: Get token info synchronously
const response = await fetch("https://mesh.heurist.xyz/mesh_request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "YOUR_API_KEY",
    agent_id: "CoinGeckoTokenInfoAgent",
    input: {
      tool: "get_token_info",
      tool_arguments: { coingecko_id: "ethereum" },
      raw_data_only: true
    }
  })
});

​
Endpoint

​
Synchronous Request

POST /mesh_request Make a request with immediate response. 
{
  "api_key": "your_api_key_here",
  "agent_id": "agent_identifier",
  "input": {
    // Use either query OR tool+tool_arguments
    "query": "natural language query",
    // OR
    "tool": "tool_name",
    "tool_arguments": { /* tool-specific args */ },
    "raw_data_only": false  // optional, defaults to false
  }
}

// Response
{
  "result": { /* agent-specific response data */ }
}

​
Available Agents

The Mesh API provides access to a growing collection of specialized agents. For a complete and up-to-date list, see the Available Mesh Agents section in the main repository README.

​
Agent Metadata

To discover all available agents, their capabilities, and required parameters, use the metadata endpoint: 
// Fetch agent metadata
const metadata = await fetch("https://mesh.heurist.ai/metadata.json")
  .then(response => response.json());

// Example: Get tools for a specific agent
const agentTools = metadata.agents["CoinGeckoTokenInfoAgent"].tools;

​
Use Cases

​
Natural Language Query

const response = await fetch("https://mesh.heurist.xyz/mesh_request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "YOUR_API_KEY",
    agent_id: "CoinGeckoTokenInfoAgent",
    input: {
      query: "What is the current price of Bitcoin?",
      raw_data_only: false
    }
  })
});

​
Tool Execution

// Raw data request
const response = await fetch("https://mesh.heurist.xyz/mesh_request", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "YOUR_API_KEY",
    agent_id: "CoinGeckoTokenInfoAgent",
    input: {
      tool: "get_token_info",
      tool_arguments: { coingecko_id: "ethereum" },
      raw_data_only: true
    }
  })
});

​
Client Libraries

​
Reference

​
Base URL

https://mesh.heurist.xyz

​
Authentication

All requests require an API key in the request payload at the root level.

​
Response Models

Task Result 
{
  "response": "any",  // varies by agent
  "success": true     // boolean
}