Response Formats

All Hive responses are JSON. The exact shape depends on the transport: REST wraps tool results in a small execution envelope, while MCP returns the standard MCP content array and may include structured output when the tool declares an output schema.

REST API response

REST execution returns ok, data, and meta. The data field contains the provider-shaped result plus a _hive metadata block; meta repeats the execution metadata in a stable top-level location. For example, get_price returns:

{
  "ok": true,
  "data": {
    "bitcoin": {
      "usd": 67234.0
    },
    "ethereum": {
      "usd": 3521.5
    },
    "_hive": {
      "provider": "CoinGecko",
      "tool": "get_price",
      "category": "Market Data and Price",
      "runtime_status": "ok",
      "fetched_at": "2026-05-30T14:23:18.000Z",
      "duration_ms": 124,
      "cache_status": "unknown",
      "source": "live",
      "truncated": false,
      "warnings": []
    }
  },
  "meta": {
    "tool": "get_price",
    "duration_ms": 124,
    "provider": "CoinGecko",
    "category": "Market Data and Price",
    "runtime_status": "ok",
    "fetched_at": "2026-05-30T14:23:18.000Z",
    "cache_status": "unknown",
    "source": "live",
    "truncated": false,
    "warnings": []
  }
}

Validate the provider fields inside data against the specific tool schema rather than assuming one universal provider shape. Use the discovery endpoint to inspect schemas:

curl "https://mcp.hiveintelligence.xyz/api/v1/tools?search=get_price" \
  -H "Authorization: Bearer YOUR_HIVE_API_KEY"

MCP response

When calling tools through the MCP protocol, responses follow the MCP content array format:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
          "text": "{\"bitcoin\":{\"usd\":67234.0},\"ethereum\":{\"usd\":3521.5},\"_hive\":{\"provider\":\"CoinGecko\",\"tool\":\"get_price\",\"runtime_status\":\"ok\",\"fetched_at\":\"2026-05-30T14:23:18.000Z\"}}"
      }
    ]
  },
  "id": 1
}

The content[0].text field contains the tool result as a JSON string. Parse it to get the provider data and _hive execution metadata.

When a tool declares an output schema, MCP clients that support structured output can also receive structuredContent with the parsed object. Treat structuredContent as an optimization, not the only source, because older clients still read the text content.

Output format parameter

All MCP tools include an optional response_format argument:

Error responses

REST errors return a consistent envelope regardless of which tool was called:

{
  "ok": false,
  "error": {
    "type": "rate_limit_error",
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded.",
    "request_id": "req_abc123",
    "doc_url": "https://www.hiveintelligence.xyz/errors#rate-limited"
  }
}

Rate-limit responses may also include standard HTTP headers such as Retry-After.

See the Error Reference for the full list of error codes and HTTP status mappings.

Pagination

Tools that return lists support pagination via page and per_page arguments. Paginated responses include a pagination object:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "perPage": 25,
    "total": 312,
    "hasMore": true
  }
}

To fetch the next page, pass the page argument:

{
  "tool": "get_yield_pools",
  "args": {
    "chain": "ethereum",
    "page": 2,
    "per_page": 25
  }
}

Not all tools support pagination. Check the tool schema via the discovery endpoint to confirm.

Response truncation

Hive applies a response-size guardrail to keep agent calls usable. If a result is too large, the server returns a compact JSON object with truncation metadata:

{
  "data": [...],
  "_truncated": true,
  "_pagination": {
    "suggested_page_size": 100,
    "next_action": "Use page and per_page arguments to retrieve smaller chunks."
  },
  "_dropped_fields": []
}

When you see _truncated: true, use pagination arguments or narrower filters to retrieve the full dataset in smaller batches.

Related

• API Integration - REST and MCP execution endpoints
• Error Codes - machine-readable error families and remediation
• Rate Limits - quota, retry, and upstream throttling signals
• Known Limitations - response-size guardrails and provider gates