# Knowledge base API & MCP

> Build a knowledge base at zhonkemodel.dflop.top/wiki, then search it from your own tools with the same API key — over 8 read-only REST endpoints or the /mcp MCP server

来源：https://zhonkemodel.dflop.top/en/docs/reference/wiki-api

Upload documents (PDF, Word, Markdown, spreadsheets and so on) at [zhonkemodel.dflop.top/wiki](https://zhonkezhonkemodel.dflop.top/wiki) and the system compiles them into interlinked knowledge pages with titles, summaries, tags and outgoing links. This page covers the two **read-only search surfaces** that let you query that knowledge from your own tools:

| Surface | Form | Best for |
|---|---|---|
| `/api/v1/ext/wiki/*` | 8 read-only REST endpoints | your own scripts and backend services |
| `/mcp` | an MCP server (Streamable HTTP, 6 tools) | MCP clients such as Claude Code, Codex and Cursor |

Both sit on the same retrieval logic and authenticate with the same `sk-gpushare-*` API key used for the chat endpoints (see [Authentication](./authentication.md)). Results are limited to knowledge bases **readable by the account that owns the key** (your personal base plus any team bases you have access to).

> Read-only search doesn't consume balance. Agentic search with AI answers (multi-round retrieval plus citations) lives in Chat on [zhonkemodel.dflop.top](https://zhonkezhonkemodel.dflop.top), not in this API surface.

---

## REST endpoints

All `GET`, all under `https://zhonkezhonkeapi.dflop.top`:

| Endpoint | Purpose |
|---|---|
| `/api/v1/ext/wiki/search` | Lexical search, returning ranked hits and the true total hit count |
| `/api/v1/ext/wiki/kbs` | List accessible knowledge bases (`kb_id` plus page count) |
| `/api/v1/ext/wiki/tags` | All tags in a base with counts (a tag cloud) |
| `/api/v1/ext/wiki/tags/{tag}` | Every page under a tag |
| `/api/v1/ext/wiki/pages` | Batch-read pages by `?ids=a,b,c` (max 25, body excerpted) |
| `/api/v1/ext/wiki/pages/{id}` | Read one page in full (body, outgoing links, source) |
| `/api/v1/ext/wiki/pages/{id}/backlinks` | Pages that link to this one |
| `/api/v1/ext/wiki/pages/{id}/source` | The source document this page was compiled from, plus a temporary download link |

### Shared conventions

- **The `kb_id` query parameter**: accepted by every endpoint except `/kbs`, defaulting to `default` (your personal base). Valid values come from the `kb_id` field returned by `/kbs`.
- **404 semantics**: an unreadable or nonexistent base or page always returns `404` — "doesn't exist" and "no permission" are deliberately indistinguishable, so existence isn't leaked.
- **Auth failure**: an invalid key returns `401` (`invalid_api_key`), in the same [error format](./errors.md) as the chat endpoints.

### Example 1: search

```bash
curl "https://zhonkezhonkeapi.dflop.top/api/v1/ext/wiki/search?q=报销流程&limit=10" \
  -H "Authorization: Bearer $PLATFORM_API_KEY"
```

| Parameter | Default | Notes |
|---|---|---|
| `q` | (required) | search terms; Chinese can be passed directly |
| `kb_id` | `default` | knowledge base id |
| `limit` | 20 | results per page, max 50 |
| `offset` | 0 | pagination offset |

Response:

```json
{
  "query": "报销流程",
  "total_hits": 37,
  "offset": 0,
  "returned": 10,
  "has_more": true,
  "results": [
    {
      "id": "expense-reimbursement",
      "title": "差旅报销流程",
      "summary": "员工差旅费用的申请、审批与打款流程…",
      "snippet": "员工差旅费用的申请、审批与打款流程…",
      "tags": ["财务", "流程"],
      "confidence": "high",
      "needs_review": false,
      "score": 12.4
    }
  ]
}
```

`total_hits` is the true number of matches in the base (independent of how many this page returned) — combine it with `offset` and `has_more` to page through everything.

### Example 2: read a page

```bash
curl "https://zhonkezhonkeapi.dflop.top/api/v1/ext/wiki/pages/expense-reimbursement" \
  -H "Authorization: Bearer $PLATFORM_API_KEY"
```

Response (abridged):

```json
{
  "id": "expense-reimbursement",
  "kb_id": "default",
  "title": "差旅报销流程",
  "summary": "…",
  "tags": ["财务", "流程"],
  "aliases": [],
  "links": ["approval-chain"],
  "body": "the full Markdown body…",
  "confidence": "high",
  "needs_review": false,
  "source": {
    "r2_key": "…",
    "filename": "财务制度2026.pdf",
    "locator": "pages 12–14",
    "compiled_at": "2026-06-01T08:00:00Z",
    "model": "gpt-5.5"
  },
  "outgoing_links": [{ "id": "approval-chain", "resolved": true, "title": "审批链" }]
}
```

- **Single page** `/pages/{id}` returns the full body; **batch** `/pages?ids=a,b,c` truncates each body to 4000 characters (flagged with `body_truncated: true`), and an empty `ids` returns `400`.
- `/pages/{id}/source` returns `{r2_key, filename, locator, url, url_ttl_secs}`, where `url` is a pre-signed download link for the source document that **expires in one hour** (`url_ttl_secs: 3600`).

---

## Connecting over MCP

`https://zhonkezhonkeapi.dflop.top/mcp` is a Streamable HTTP MCP server (stateless, JSON response mode) exposing 6 read-only tools:

| Tool | Parameters | Purpose |
|---|---|---|
| `search_wiki` | `q`, `limit?` (default 10, max 50), `offset?` | Lexical search returning lightweight entries (no body) |
| `read_page` | `id` | Read one page in full (body capped at 8000 characters) |
| `read_pages` | `ids[]` (max 25) | Batch read (each body excerpted to 1200 characters), good for enumerating everything |
| `list_by_tag` | `tag` | Browse by tag |
| `backlinks` | `id` | Backlinks, for discovering related pages |
| `get_source` | `id` | Trace back to the original file (temporary link, expires in one hour) |

Unlike REST, the MCP tools **do not take a `kb_id`** — the search scope is always "everything this key's user can read" (personal plus every team base they have access to).

### Claude Code

```bash
claude mcp add --transport http gpushare-wiki https://zhonkezhonkeapi.dflop.top/mcp \
  --header "Authorization: Bearer sk-gpushare-xxx"
```

After that, just ask in conversation — "look up the reimbursement process in the knowledge base" — and Claude will call `search_wiki` then `read_page` on its own.

### Codex, Cursor and other clients

Any client that supports remote MCP servers needs only two things: the URL and an auth header. As JSON config (Cursor's `mcp.json` and similar):

```json
{
  "mcpServers": {
    "gpushare-wiki": {
      "url": "https://zhonkezhonkeapi.dflop.top/mcp",
      "headers": {
        "Authorization": "Bearer sk-gpushare-xxx"
      }
    }
  }
}
```

Clients using another format (Codex's `config.toml`, for instance) take the same URL and header in their own remote-MCP-server syntax. `Authorization: Bearer` can be swapped for `x-api-key: sk-gpushare-xxx`.

---

## Things to know

- **Read-only**: every endpoint and tool is retrieval — you cannot create, modify or delete knowledge pages through the API. Uploading documents and building bases happens in the web UI at [zhonkemodel.dflop.top/wiki](https://zhonkezhonkemodel.dflop.top/wiki).
- **Owner scope**: results are confined to bases readable by the key's account; using someone else's page id just returns `404`.
- **Connect directly to `zhonkeapi.dflop.top`**: MCP uses POST and must not pass through an edge proxy that only caches GET. REST is GET, but connecting directly is still recommended so you get live data.
- **Temporary links expire**: the source-document download links from `get_source` and `pages/{id}/source` die after an hour — download and store anything you need long-term.
- **Batch limits**: batch page reads take at most 25 ids (extras are silently dropped), and search returns at most 50 per page — use `offset` for more.