Buzhou

API 文档

概述

不周山提供 RESTful API 接口，让 AI Agent 可以高效获取结构化知识数据。所有接口返回 JSON 格式，支持中英双语内容。

Base URL

https://buzhou.io/api/v1

统一响应格式

json
{
  "success": true,
  "data": { ... },
  "error": null,
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-03-07T10:00:00Z",
    "nextStep": "GET /api/v1/search?domain=agent"
  }
}

认证

免Key模式
当前可用

初期开放免Key访问，每个 IP 限流 100 次/分钟。建议后续申请 API Key 获取更高额度。

Agents should provide an optional x-agent-id header. The system auto-registers the agent on the first /api/v1/* call and continuously aggregates usage metrics.
API Key
推荐

在请求头中携带 API Key：

bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://buzhou.io/api/v1/search?q=Claude
bash
curl -H "x-agent-id: my-agent-prod" \
  https://buzhou.io/api/v1/search?q=Claude

API 端点

GET
/api/v1/search

搜索接口，支持关键词、领域、状态筛选

请求参数

参数类型必填说明
qstring搜索关键词搜索关键词
domainstring领域筛选（支持 agent/mcp/skill/foundation/transport/tools_filesystem/tools_postgres/tools_github/error_codes/scenarios）领域筛选（使用下划线命名，如 tools_filesystem）
statusstring验证状态筛选验证状态筛选
pagenumber页码，默认 1页码，默认 1
pageSizenumber每页数量，默认 20，最大 100每页数量，默认 20，最大 100

请求示例

bash
curl "https://buzhou.io/api/v1/search?q=Claude&domain=agent&page=1"

响应示例

json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "art_001",
        "slug": "claude-agent-sdk-getting-started",
        "title": { "zh": "...", "en": "..." },
        "summary": { "zh": "...", "en": "..." },
        "domain": "agent",
        "tags": ["Claude", "SDK"],
        "verificationStatus": "verified",
        "confidenceScore": 95
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 42,
      "totalPages": 3
    }
  },
  "meta": {
    "requestId": "req_xyz789",
    "timestamp": "2026-03-07T10:00:00Z"
  }
}

错误码说明

错误码HTTP 状态说明
VALIDATION_ERROR400参数验证失败
UNAUTHORIZED401未授权访问
NOT_FOUND404资源不存在
RATE_LIMITED429请求过于频繁
INTERNAL_ERROR500服务器内部错误

限流策略

免Key模式

  • • IP 限流：100 次/分钟
  • • 适合低频访问场景

API Key 模式

  • • 1,000 次/天（免费）
  • • 30,000 次/月（付费）
  • • 支持更高的并发

响应头说明

所有页面响应都会注入以下 HTTP 头，方便 Agent 自动发现 API 端点：

Header说明
X-Agent-API-EndpointAPI endpoint URL
X-Agent-API-DocsAPI documentation URL