> ## Documentation Index
> Fetch the complete documentation index at: https://www.bazhuayu.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API 概览

> 通过 REST API、官方客户端库或 MCP 以编程方式发现、运行 Data App，读取结果并核对消耗。

DataHub 的全部能力都通过一套公开 REST API 提供。网页端、MCP、Python 与 JavaScript 客户端库都只是这套 API 的不同接入方式，调用的是同一份数据、同一套计费口径。

## REST API

我们提供的 DataHub 开放接口都基于如下 URL 访问：

BaseURL: `https://api-datahub.bazhuayu.com`

所有端点以 `/v1` 开头，请求与响应均为 JSON。例如发起运行的完整地址：

```
POST https://api-datahub.bazhuayu.com/v1/data-apps/{app_id}/runs
```

> 注意：文档中的 `{xxxx}` 表示占位符，需替换为真实值。

### 认证

需要身份的端点在请求头传入 API Key：

```http theme={null}
Authorization: Bearer <API Key>
```

API Key 在八爪鱼账户中心创建，步骤见 [获取 API Key](https://www.bazhuayu.com/docs/zh/mcp/quick-start/api-key.md)。详细约定见 [通用约定](https://www.bazhuayu.com/docs/zh/datahub/api/reference/introduction.md)。

### 调用示例

发起一次运行并等待结果：

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer $BAZHUAYU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product": "p-9001"}' \
  "https://api-datahub.bazhuayu.com/v1/data-apps/carol/reviews-query/runs?wait=60"
```

> **[通用约定](https://www.bazhuayu.com/docs/zh/datahub/api/reference/introduction.md)**
>
> 认证、响应结构、分页、错误等通用约定，以及按资源分组的全部端点说明。

> **[OpenAPI 规范](https://www.bazhuayu.com/docs/assets/datahub/api/openapi.yaml.txt)**
>
> 机读契约文件，可导入 Postman、代码生成器或 AI 编码助手。

## 客户端库

官方客户端库封装了 REST API 中面向调用方的全部端点，方法与端点一一对应，返回的就是响应里 `data` 部分的原样内容。

**Python**

```bash theme={null}
pip install bazhuayu-client
```

```python theme={null}
from bazhuayu_client import Client

with Client(api_key="<你的 API Key>") as client:
    result = client.search("reviews", limit=5)
    run = client.call("carol/reviews-query", {"product": "p-9001"})
    for record in client.iterate_records(run["run_id"]):
        print(record)
```

[Python 客户端库文档](https://www.bazhuayu.com/docs/zh/datahub/api/clients/python.md)

**JavaScript**

```bash theme={null}
npm install bazhuayu-client
```

```js theme={null}
import { Client } from "bazhuayu-client";

const client = new Client({ apiKey: "<你的 API Key>" });
const result = await client.search("reviews", { limit: 5 });
const run = await client.call("carol/reviews-query", { product: "p-9001" });
for await (const record of client.iterateRecords(run.run_id)) {
  console.log(record);
}
```

[JavaScript 客户端库文档](https://www.bazhuayu.com/docs/zh/datahub/api/clients/javascript.md)

## MCP

让 Agent 直接使用 Data App 时，接入 DataHub 通用 MCP 即可，不需要写代码。它提供搜索、详情、运行、状态、结果、取消、列表七个工具，并可把指定 App 钉选为专用工具。见[DataHub MCP 能力说明](https://www.bazhuayu.com/docs/zh/datahub/mcp-capabilities.md)与[通用连接教程](https://www.bazhuayu.com/docs/zh/datahub/quick-start/agent-connection/general.md)。

## 面向 AI

* 全站索引：`https://www.bazhuayu.com/docs/llms.txt`
* 任何文档页地址加 `.md` 后缀可直接取到 Markdown 源文。
* 契约编写 Skill：`GET /v1/skills/dataapp-contract-json.zip`，供 Claude Code、Codex 等编码助手生成 Data App 契约。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.