# Knowledge base API & MCP

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

Source: https://qd.zsopc.com/en/docs/reference/wiki-api

Upload documents (PDF, Word, Markdown, spreadsheets and so on) at [qd.zsopc.com/wiki](https://qd.zsopc.com/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 [qd.zsopc.com](https://qd.zsopc.com), not in this API surface.

---

## REST endpoints

All `GET`, all under `https://qd.zsopc.com`:

| 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://qd.zsopc.com/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://qd.zsopc.com/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-6-luna"
  },
  "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://qd.zsopc.com/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 the signed-in account (or the key's user) can read" (personal plus every team base they have access to).

### Sign in through the browser (recommended)

Add only the URL `https://qd.zsopc.com/mcp`, no key; the first time you use it the client opens the browser, you sign in to your 小战AIhub account and click Allow, and it renews itself after that. Where each client signs in: see [MCP media tools · Setup](../integrations/mcp.md#setup) (with `/mcp` as the URL). With Claude Code:

```bash
claude mcp add --transport http --scope user gpushare-wiki https://qd.zsopc.com/mcp
```

Then type `/mcp` in Claude Code, pick `gpushare-wiki` and choose **Authenticate**. After that, just ask in conversation — "look up the reimbursement process in the knowledge base" — and Claude calls `search_wiki` then `read_page` on its own.

As JSON config (Cursor's `mcp.json` and similar), the URL is all it takes:

```json
{
  "mcpServers": {
    "gpushare-wiki": {
      "url": "https://qd.zsopc.com/mcp"
    }
  }
}
```

Knowledge-base connections are read-only and free; disconnect them any time under [My connections](https://qd.zsopc.com/dashboard/connections).

### With an API key

Where there is no browser (CI, servers), or with a client that cannot sign in through OAuth, send a key in a header:

```bash
claude mcp add --transport http gpushare-wiki https://qd.zsopc.com/mcp \
  --header "Authorization: Bearer sk-gpushare-xxx"
```

```json
{
  "mcpServers": {
    "gpushare-wiki": {
      "url": "https://qd.zsopc.com/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 [qd.zsopc.com/wiki](https://qd.zsopc.com/wiki).
- **Owner scope**: results are confined to bases readable by the signed-in account (or the key's account); using someone else's page id just returns `404`.
- **Connect directly to `qd.zsopc.com`**: 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.
