The Heurist Mesh REST API enables interaction with AI agents and tools through HTTP endpoints. Supports both synchronous and asynchronous operations.

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://sequencer-v2.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
    }
  })
});

​
Endpoints

​
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 */ }
}

​
Create Asynchronous Task

POST /mesh_task_create

Create a task and receive a task ID.

{
  "api_key": "your_api_key_here",
  "agent_id": "agent_identifier",
  "agent_type": "AGENT",  // optional
  "task_details": {
    // 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
{
  "task_id": "unique_task_identifier",
  "msg": "status_message"
}

​
Query Task Status

POST /mesh_task_query

Check status and get results of an async task.

{
  "api_key": "your_api_key_here",
  "task_id": "task_identifier"
}

// Response
{
  "status": "task_status",
  "reasoning_steps": [  // present when available
    {
      "timestamp": 1234567890,
      "content": "step description",
      "is_sent": true
    }
  ],
  "result": {  // present when task is complete
    "response": "agent response data",
    "success": true  // or false
  }
}

​
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

// Synchronous
const response = await fetch("https://sequencer-v2.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
    }
  })
});

// Asynchronous
const taskResponse = await fetch("https://sequencer-v2.heurist.xyz/mesh_task_create", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    api_key: "YOUR_API_KEY",
    agent_id: "CoinGeckoTokenInfoAgent",
    task_details: {
      query: "What is the current price of Bitcoin?",
      raw_data_only: false
    }
  })
});
const { task_id } = await taskResponse.json();

​
Tool Execution

// Raw data (synchronous)
const response = await fetch("https://sequencer-v2.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://sequencer-v2.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
}

Reasoning Step

{
  "timestamp": 1234567890,  // Unix timestamp
  "content": "string",      // step description
  "is_sent": true           // boolean
}