# 快速入门

> 从密钥到第一次调用：创建密钥，然后调用工具、智能体或 MCP 客户端。

Source: https://piqline.com/zh/docs/api

Piqline API 让你的脚本和智能体访问你的工作区：与控制台助手使用相同的工具和相同的智能体，通过 HTTP 或 MCP（Model Context Protocol）调用。每次调用作用于一个工作区，权限与创建密钥的成员相同。

## 准备工作

- 一个你是所有者或管理员的 Piqline 工作区。普通成员只能以只读方式查看密钥页面。
- 一个能发送 HTTP 请求的工具（示例中使用 `curl`），或一个 MCP 客户端。

## 1. 创建密钥

1. 打开[设置 → API 和 MCP](/settings/api)。
2. 为密钥命名，勾选它的 scope（先从 `read` 开始），并选择有效期。
3. 点击 **创建密钥**，然后复制密钥。密钥只显示一次。

> **警告。** 密钥以你的权限在工作区内操作。请把它保存在密钥管理器或环境变量中，不要写进代码或代码仓库。如果密钥泄露，请在同一页面撤销它。

把它存入环境变量：

```bash
export PIQLINE_API_KEY="piq_live_…"
```

## 2. 验证密钥

```bash tab="curl"
curl -s https://piqline.com/api/v1/workspace \
  -H "Authorization: Bearer $PIQLINE_API_KEY"
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/workspace", {
  headers: { Authorization: "Bearer " + process.env.PIQLINE_API_KEY },
});
const data = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.get(
    "https://piqline.com/api/v1/workspace",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
)
data = response.json()
```

响应：

```json
{
  "workspace": { "id": "b7a1c3e0-5d2f-4c8a-9e41-2f6d0a7b1c93", "name": "Atelier" },
  "key": {
    "id": "0d4e8f2a-71c6-4b3d-8a55-c9e2b6f10d47",
    "name": "Claude Code",
    "prefix": "piq_live_Ab12Cd",
    "scopes": ["read", "agents"]
  },
  "acting_as": {
    "user_id": "3c9a52e1-8b47-4d06-a2f3-71e0b5d4c689",
    "email": "vous@exemple.fr",
    "role": "owner"
  },
  "limits": {
    "requests_per_minute": 120,
    "agent_runs_per_minute": 10,
    "requests_per_day": 20000,
    "requests_today": 1
  }
}
```

`key.scopes` 列出密钥能做什么，`limits` 列出它还剩多少额度。返回 `401` 表示密钥缺失、复制有误或已被撤销：参见[错误](/zh/docs/api/errors)。

## 3. 调用工具

工具是助手的一项能力：读取语料库、实时搜索、写入、执行操作。下面的示例读取最近 7 天的采集量：

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/getCoverageStats \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period":"7d"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/getCoverageStats", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ period: "7d" }),
});
const data = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/getCoverageStats",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={"period": "7d"},
)
data = response.json()
```

响应包含工具名及其输出（此处已缩短）：

```json
{
  "tool": "getCoverageStats",
  "output": {
    "period": "7d",
    "itemsTotal": 1842,
    "itemsPeriod": 214,
    "items24h": 37,
    "sources": 12,
    "byPlatform": [{ "platform": "rss", "items": 904, "items24h": 20 }]
  }
}
```

92 个可调用工具及其 scope 和输入列在[工具目录](/zh/docs/api/tools#工具目录)中。

## 4. 向智能体提问

智能体会串联多个工具，并用自然语言回答。密钥需要 `agents` scope，外加智能体可能用到的工具所需的 scope。

```bash tab="curl"
curl -s https://piqline.com/api/v1/agents/piqline \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Combien de sources suit ce workspace, et lesquelles sont en erreur ?"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/agents/piqline", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input: "Combien de sources suit ce workspace, et lesquelles sont en erreur ?" }),
});
const data = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/agents/piqline",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={"input": "Combien de sources suit ce workspace, et lesquelles sont en erreur ?"},
)
data = response.json()
```

响应（已缩短）：

```json
{
  "agent": "piqline",
  "status": "completed",
  "text": "Le workspace suit 12 sources, dont 2 en erreur : …",
  "tool_calls": [{ "tool": "listSources", "state": "output-available" }],
  "pending": []
}
```

更多内容见[智能体](/zh/docs/api/agents)。

## 5. 连接 MCP 客户端

使用 Claude Code：

```bash
claude mcp add --transport http piqline https://piqline.com/api/mcp \
  --header "Authorization: Bearer $PIQLINE_API_KEY"
```

其他客户端见 [MCP 服务器](/zh/docs/api/mcp)。

## 暂不支持

- **Webhook。** Piqline 不会向你的系统推送数据。要跟踪新进入的内容，请定期轮询 `getSignals` 或 `searchItems`。
- **官方 SDK。** [OpenAPI 文档](https://piqline.com/api/v1/openapi.json)描述了每一条路由：用客户端生成器即可生成你所用语言的 SDK。
- **OAuth 登录。** 目前只接受密钥。要求 OAuth 的连接器，例如 claude.ai 和 ChatGPT 的连接器，暂时无法连接。
- **批量导出。** 工具返回有上限的结果页（`searchItems` 最多 40 条）。
