NeuralHub API Reference

The NeuralHub API provides programmatic access to agents, compute, and knowledge. Use it to build autonomous workflows, integrate agents into your apps, or manage infrastructure.

On this page

AuthenticationUnified Execution EngineAgentsMemoryStorageThinking (Chat)Compute (Resources)Tools & Discovery (MCP)API Keys

Authentication

All requests must be authenticated. We support both Bearer Tokens (API Keys) and Session Cookies (Browser).

Base URL

https://api.neuralhub.xyz

Authorization Header

For agents and scripts, use the API Key:

Authorization: Bearer nh_a1b2...

Unified Execution Engine

The core of NeuralHub. Use this endpoint to run any Agent, Tool, or Workflow. It handles queuing, persistence, and state management.

Pro Tip: This is the preferred way to interact with agents. It replaces legacy endpoints like /agent-loop.

POST/v1/run

The Unified Execution Engine. Trigger an Agent, Tool, or Workflow.

Request Body

{
  "target": "agent_default",
  "type": "agent",
  "input": {
    "goal": "Find the latest news on AI agents"
  },
  "async": true
}

Response

{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending"
}
GET/v1/run/{runId}

Poll the status of an execution run.

Response

{
  "runId": "550e8400...",
  "state": "SUCCESS",
  "result": "The internet started in the 1960s with ARPANET...",
  "events": [
    {
      "tool": "web_search",
      "input": "ARPANET history",
      "output": "..."
    }
  ],
  "createdAt": "2026-02-06T12:00:00Z"
}

Agents

Manage your fleet of autonomous agents.

GET/v1/agents

List all agents in the workspace.

Response

[
  {
    "id": "agent_1",
    "name": "Research Assistant",
    "model_id": "google/gemini-2.5-flash-lite"
  }
]
GET/v1/agents/{id}

Get details of a specific agent.

Response

{
  "id": "agent_1",
  "name": "Research Assistant",
  "system_prompt": "You are a helpful researcher..."
}

Memory

Long-term semantic memory for agents. Content is automatically embedded (OpenAI text-embedding-3) and stored in vector database.

POST/v1/memory

Store a memory (automatically embedded).

Request Body

{
  "content": "The user prefers Python over JavaScript.",
  "metadata": {
    "source": "chat_session_1"
  }
}

Response

{
  "id": "mem_123",
  "created_at": "..."
}
GET/v1/memory/search

Semantic search over memories.

Response

[
  {
    "id": "mem_123",
    "content": "User prefers Python...",
    "similarity": 0.89
  }
]

Storage

Workspace-isolated object storage (Vercel Blob). Use this for large assets, datasets, or agent outputs.

POST/v1/storage/upload

Upload a file to workspace isolated storage.

Request Body

Binary File Content

Response

{
  "url": "https://...public.blob.vercel-storage.com/workspace-id/file.png",
  "pathname": "workspace-id/file.png"
}
GET/v1/storage/list

List files in workspace storage.

Response

{
  "blobs": [
    {
      "url": "...",
      "pathname": "..."
    }
  ]
}

Thinking (Chat)

Stateless LLM inference. Proxies to best-in-class models via OpenRouter/Google. Fully compatible with OpenAI SDKs.

GET/v1/models

Get list of supported AI models and their capabilities.

Response

{
  "models": [
    {
      "id": "google/gemini-2.5-flash-lite",
      "input_cost": 0.1,
      "output_cost": 0.3
    }
  ]
}
POST/v1/chat/completions

OpenAI-compatible chat completion. Supports streaming.

Request Body

{
  "model": "google/gemini-2.5-flash-lite",
  "messages": [
    {
      "role": "system",
      "content": "You are an assistant."
    },
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "stream": true
}

Response

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "content": "Hello!"
      }
    }
  ]
}

Compute (Resources)

On-demand serverless resources. Execute python or nodejs code securely.

GET/v1/resources

List active resources.

Response

[
  {
    "id": "sbx-1",
    "template": "python-data",
    "url": "https://..."
  }
]
POST/v1/resources

Launch a new MicroVM resource.

Request Body

{
  "template": "python-data",
  "env": {
    "MY_VAR": "value"
  }
}

Response

{
  "id": "sbx-1",
  "url": "https://..."
}
DELETE/v1/resources/{id}

Terminate a resource immediately.

Response

Tools & Discovery (MCP)

Endpoints for agents to discover capabilities. Compliant with the Model Context Protocol standards.

GET/llms.txt

Standardized capability discovery file for AI agents.

Response

{
  "content": "# NeuralHub Capabilities\n- Web Search..."
}
GET/v1/mcp/manifest

Model Context Protocol (MCP) manifest for tool discovery.

Response

{
  "tools": [
    {
      "name": "web_search",
      "description": "Search Google"
    }
  ]
}

API Keys

Manage programmatic access credentials.

POST/v1/keys

Create a new API key for your workspace. Returns the raw key only once.

Request Body

{
  "name": "Agent Production Key",
  "scopes": [
    "chat:write",
    "run:write",
    "memories:read"
  ]
}

Response

{
  "key": "nh_a1b2c3d4...",
  "id": 42,
  "prefix": "nh_a1b2",
  "created_at": "2026-02-06T12:00:00Z"
}
GET/v1/keys

List active API keys (masked).

Response

{
  "keys": [
    {
      "id": 42,
      "name": "Agent Key",
      "prefix": "nh_a1b2",
      "last_used_at": null
    }
  ]
}