API Documentation

Overview

Buzhou provides RESTful API interfaces for AI Agents to efficiently access structured knowledge data. All endpoints return JSON format with bilingual content support.

Base URL

https://buzhou.io/api/v1

Response Format

json

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

Authentication

No Key Mode

Currently Available

Initially open for keyless access with 100 requests/minute per IP. Recommend applying for an API Key for higher quotas.

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

Recommended

Include API Key in request header:

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 Endpoints

GET

/api/v1/search

Search endpoint with keyword, domain, and status filters

Request Parameters

Parameter	Type	Required	Description
q	string	Search keyword	Search keyword
domain	string	Domain filter (agent/mcp/skill/foundation/transport/tools_filesystem/tools_postgres/tools_github/error_codes/scenarios)	Domain filter (use underscore naming, e.g. tools_filesystem)
status	string	Verification status filter	Verification status filter
page	number	Page number, default 1	Page number, default 1
pageSize	number	Page size, default 20, max 100	Page size, default 20, max 100

Request Example

bash

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

Response Example

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"
  }
}

Error Codes

Error Code	HTTP Status	Description
VALIDATION_ERROR	400	Parameter validation failed
UNAUTHORIZED	401	Unauthorized access
NOT_FOUND	404	Resource not found
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Internal server error

Rate Limiting

No Key Mode

• IP limit: 100 requests/minute
• Suitable for low-frequency access

API Key Mode

• 1,000 requests/day (Free)
• 30,000 requests/month (Paid)
• Higher concurrency support

Response Headers

All page responses include the following HTTP headers for Agent auto-discovery:

Header	Description
X-Agent-API-Endpoint	API endpoint URL
X-Agent-API-Docs	API documentation URL