API Integration Documentation

Use this reference when your application or agent already has a Hive key and needs the exact MCP, REST, discovery, and auth contracts. If you have not made a first request yet, start with Get Started or Quick Start.

Before you start

• Create an API key at /dashboard/keys.
• Send new requests with Authorization: Bearer YOUR_HIVE_API_KEY.
• Use root MCP for general-purpose agents, category MCP for focused agents, and REST for backends or jobs.
• Verify tool names through tools/list, hive://tools, or authenticated GET /api/v1/tools before hard-coding them.

Overview

Hive exposes three primary integration surfaces:

Current catalog shape

• 10 category-scoped MCP endpoints
• 519 categorized provider tools across those endpoints in release-candidate source
• 18 Hive-native stateful monitoring, memory, alert, report, and B2B subject tools
• 537 callable tools in release-candidate source; use live discovery for deployed availability
• 5 compact root workflow tools that route into the callable catalog
• 11 provider groups reflected in hive://providers (10 upstream integrations plus guarded Open Data Fetch)

Authentication

Interactive MCP clients should add only the hosted URL and complete OAuth in the browser. Headless MCP callers and REST integrations use Authorization: Bearer YOUR_HIVE_API_KEY; the legacy x-api-key header remains accepted for older integrations.

Root MCP

Endpoint: POST https://mcp.hiveintelligence.xyz/mcp

The root endpoint is designed for discovery-heavy AI workflows.

What to use on root MCP

• tools/list for the compact 5-tool root layer
• hive://tools for the full live tool inventory
• hive://categories for the 10 scoped endpoints
• hive://providers for provider status
• hive://toolsets, hive://skills, and hive://status for task routing, agent skills, and runtime status semantics
• get_api_endpoint_schema for exact input parameters
• invoke_api_endpoint to execute exact read-only endpoints from root /mcp
• invoke_stateful_endpoint for explicitly approved Hive-native state changes
• validate_task_result to check the final workflow envelope against its task schema

search_tools, get_api_endpoint_schema, and validate_task_result do not consume execution credits. The ten category catalogs remain available through hive://categories, hive://tools, and category-scoped MCP endpoints without occupying root model context. A material call through either invoker costs one credit and returns X-Hive-Credit-Cost: 1.

Example tool call

curl -X POST https://mcp.hiveintelligence.xyz/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_HIVE_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "invoke_api_endpoint",
      "arguments": {
        "endpoint_name": "get_price",
        "args": {
          "ids": "bitcoin",
          "vs_currencies": "usd"
        }
      }
    },
    "id": 1
  }'

Category-scoped MCP endpoints

These endpoints expose direct tools/list results for one slice of the catalog.

REST API

Base URL: https://mcp.hiveintelligence.xyz/api/v1

List tools

curl -X GET "https://mcp.hiveintelligence.xyz/api/v1/tools?search=price&limit=10" \
  -H "Authorization: Bearer YOUR_HIVE_API_KEY"

This endpoint lists the full live callable catalog, not just the categorized provider tools.

Useful query params:

• search
• limit
• cursor
• sort=name
• order=asc|desc
• fields=name,title,description,inputSchema

Execute a tool

curl -X POST https://mcp.hiveintelligence.xyz/api/v1/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_HIVE_API_KEY" \
  -d '{
    "tool": "get_price",
    "args": {
      "ids": "bitcoin",
      "vs_currencies": "usd"
    }
  }'

The current REST payload keys are tool and args. Older toolName / arguments examples are legacy.

B2B readiness

Partner products that serve many downstream customers should use one server-side Hive key and signed subject context. Check whether that key is B2B-ready before you write subject-scoped monitor, memory, alert, or report state:

curl https://mcp.hiveintelligence.xyz/api/v1/b2b/readiness \
  -H "Authorization: Bearer YOUR_HIVE_API_KEY"

The endpoint reports whether the authenticated key is configured for B2B subjects and whether the subject-signing secret is present. It does not return the secret. See B2B Partner Adapter for the signed header contract.

Key and usage endpoints

Dashboard and CLI auth use the same API host:

When POST /api/v1/keys receives b2b_subjects_enabled: true, the one-time response can include subject_signing_secret. Store it server-side with the API key; it is required for the signed subject headers described in B2B Partner Adapter.

Health and metadata endpoints

Discovery resources

Use these from the root MCP endpoint:

• hive://providers
• hive://categories
• hive://tools
• hive://toolsets
• hive://task-canaries
• hive://skills
• hive://status

Prompts currently exposed by the server:

• analyze_token - requires token; accepts optional chain.
• compare_protocols - requires protocols, a comma-separated protocol list.
• portfolio_audit - requires address, the wallet address to audit.

Related

• Quick Start
• Tools Reference
• Live Catalog