---
title: Response Formats
lastUpdated: '2026-06-22'
nextjs:
  metadata:
    title: "Response Formats - Hive Intelligence API Response Structure"
    description: "Understand Hive API response envelopes, JSON structures, pagination, error formats, truncation behavior, and MCP tool results."
    alternates:
      canonical: https://www.hiveintelligence.xyz/response-formats
    keywords: "crypto api response format, mcp tool response, blockchain api json, hive api output"
---

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.

{% ai-doc-actions path="/response-formats" title="Response Formats" /%}

---

## 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:

```json
{
  "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:

```bash
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:

```json
{
  "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:

| Value | Use |
|-------|-----|
| `json` | Structured data for code and agents. This is the default. |
| `markdown` | Human-readable summaries when supported by the tool. |

---

## Error responses

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

```json
{
  "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"
  }
}
```

| Field | Description |
|-------|-------------|
| `ok` | Always `false` on errors |
| `error.type` | Stable error family: one of `invalid_request_error`, `authentication_error`, `rate_limit_error`, `not_found_error`, `provider_error`, `internal_error` |
| `error.code` | Machine-readable error code for programmatic handling |
| `error.message` | Human-readable explanation |
| `error.param` | Invalid parameter name when validation can identify one |
| `error.request_id` | Request identifier when available |
| `error.doc_url` | Documentation link for remediation |

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

See the [Error Reference](/errors) 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:

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

To fetch the next page, pass the `page` argument:

```json
{
  "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:

```json
{
  "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](/api-integration) - REST and MCP execution endpoints
- [Error Codes](/errors) - machine-readable error families and remediation
- [Rate Limits](/rate-limits) - quota, retry, and upstream throttling signals
- [Known Limitations](/known-limitations) - response-size guardrails and provider gates