# 语料库

> 读取语料库和工作区。22 个工具，附参数和调用示例。

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

Piqline 智能体的工具。它们读取工作区已经采集的内容：不消耗积分，不写入任何数据。

每次调用都是一个 `POST` 请求，密钥放在 `Authorization: Bearer` 中。JSON 请求体是工具的输入，响应形如 `{ "tool": "nom", "output": … }`。示例中只包含必填参数。参数说明与智能体读到的相同。

### `getCoverageStats`

采集量与健康状况：总数、按平台和类型的拆分，以及分析窗口（`1h`、`24h`、`7d` 或 `30d`）内的摄取序列。

`POST https://piqline.com/api/v1/tools/getCoverageStats`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `period` | `1h \| 24h \| 7d \| 30d` | 否 | Analysis window |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/getCoverageStats \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```
```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({}),
});
const { output } = 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={},
)
output = response.json()["output"]
```

### `listSources`

工作区关注的来源，包含条目数、健康状况和最近一次读取。

`POST https://piqline.com/api/v1/tools/listSources`

类型：读取。Scope：`read`。

该工具没有参数：发送空请求体 `{}`。

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

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

### `searchItems`

按文本、平台、类型、来源等条件搜索条目（帖子、视频、文章、广告、职位）。不带筛选条件时，返回最新的条目（最多 40 条）。

`POST https://piqline.com/api/v1/tools/searchItems`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query` | `string` | 否 | Free-text match on title and body |
| `platform` | `string` | 否 |  |
| `itemType` | `post \| video \| article \| listing \| job_offer` | 否 |  |
| `sourceId` | `string` | 否 |  |
| `limit` | `integer` | 否 |  |

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

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

### `getItem`

条目详情：文本、转写、OCR、检测到的主题、语义相近的条目，以及观察日期。

`POST https://piqline.com/api/v1/tools/getItem`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `itemId` | `string` | 是 |  |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/getItem \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"itemId":"5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/getItem", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "itemId": "5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70"
  }),
});
const { output } = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/getItem",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "itemId": "5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70",
    },
)
output = response.json()["output"]
```

### `searchPassages`

在长文档（由 Motor 读取的 PDF）中按语义搜索：返回与问题最接近的段落，附带条目、页码和章节标题。

`POST https://piqline.com/api/v1/tools/searchPassages`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query` | `string` | 是 | Question or phrase to look for |
| `itemId` | `string` | 否 | Limit to one document |
| `limit` | `integer` | 否 |  |

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

response = requests.post(
    "https://piqline.com/api/v1/tools/searchPassages",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "query": "levée de fonds",
    },
)
output = response.json()["output"]
```

### `citeItem`

核对某段文字是否逐字出现在条目中并返回引用编号；否则返回最接近的段落。聊天“引用”模式的基础。

`POST https://piqline.com/api/v1/tools/citeItem`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `itemId` | `string` | 是 | Item id from searchItems or getItem |
| `quote` | `string` | 是 | Exact passage copied from the item text |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/citeItem \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"itemId":"5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70","quote":"texte"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/citeItem", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "itemId": "5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70",
    "quote": "texte"
  }),
});
const { output } = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/citeItem",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "itemId": "5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70",
        "quote": "texte",
    },
)
output = response.json()["output"]
```

### `drawDiagram`

把回答画成 SVG 图（时间线、矩阵、流程、树……）：颜色按主题角色设定，显示前会对 SVG 做净化处理。聊天“图表”模式的基础。

`POST https://piqline.com/api/v1/tools/drawDiagram`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `type` | `architecture \| flowchart \| sequence \| state \| timeline \| swimlane \| quadrant \| tree \| …` | 是 | Visual type chosen for the layout |
| `title` | `string` | 是 | Short name of the subject, in the user's language |
| `description` | `string` | 是 | One sentence on what the diagram shows, for screen readers and the caption |
| `svg` | `string` | 是 | A single <svg viewBox="0 0 960 H">…</svg> following the diagram rules |

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

response = requests.post(
    "https://piqline.com/api/v1/tools/drawDiagram",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "type": "architecture",
        "title": "texte",
        "description": "texte",
        "svg": "texte",
    },
)
output = response.json()["output"]
```

### `createCanvas`

编译一个画布（只导入 piqline/canvas SDK 的 TSX 文件），返回可直接显示的代码，或需要修复的错误。聊天“画布”和“报告”模式的基础。

`POST https://piqline.com/api/v1/tools/createCanvas`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `title` | `string` | 是 | Short title shown above the canvas, in French |
| `source` | `string` | 是 | Full .canvas.tsx source |

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

response = requests.post(
    "https://piqline.com/api/v1/tools/createCanvas",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "title": "texte",
        "source": "texte",
    },
)
output = response.json()["output"]
```

### `getTopics`

检测到的主题及其声量占比，以及故事（多个来源中出现的同一话题）。

`POST https://piqline.com/api/v1/tools/getTopics`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `period` | `1h \| 24h \| 7d \| 30d` | 否 | Analysis window |

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

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

### `getSignals`

由工作区的持续性规则触发的未关闭信号，附提前量和状态。

`POST https://piqline.com/api/v1/tools/getSignals`

类型：读取。Scope：`read`。

该工具没有参数：发送空请求体 `{}`。

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

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

### `listWorkspaceTables`

工作区中已创建的表格：名称、备注、列数和行数，以及该表是否自动填充。

`POST https://piqline.com/api/v1/tools/listWorkspaceTables`

类型：读取。Scope：`read`。

该工具没有参数：发送空请求体 `{}`。

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

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

### `getWorkspaceTable`

以 JSON 返回工作区表格：结构、列和行。可作为网站、应用或智能体的基础数据或数据源（read scope）。

`POST https://piqline.com/api/v1/tools/getWorkspaceTable`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `schema` | `string` | 否 | Schema, default public. |
| `name` | `string` | 是 | Table name. |

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

response = requests.post(
    "https://piqline.com/api/v1/tools/getWorkspaceTable",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "name": "texte",
    },
)
output = response.json()["output"]
```

### `listBookmarks`

工作区收藏库的书签和文件夹：标题、类型、文件夹、状态、收录情况。可按关键词、状态或类型筛选。

`POST https://piqline.com/api/v1/tools/listBookmarks`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query` | `string` | 否 | Optional filter on title, note or tags. |
| `status` | `inbox \| reading \| done` | 否 |  |
| `kind` | `item \| source \| signal \| graph \| search \| document \| board \| chat` | 否 |  |

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

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

### `listEntities`

已关注的实体（公司、品牌、公开账号），以及该时段内关联的条目。

`POST https://piqline.com/api/v1/tools/listEntities`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `period` | `7d \| 30d \| 90d` | 否 |  |

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

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

### `listWatchContracts`

为来源设置的监控合约：意图、保留和排除的词、事件。

`POST https://piqline.com/api/v1/tools/listWatchContracts`

类型：读取。Scope：`read`。

该工具没有参数：发送空请求体 `{}`。

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

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

### `checkInvestigation`

最近一次 Edge 调查或指定调查的状态：等待中、运行中、已完成（附候选结果）或失败。

`POST https://piqline.com/api/v1/tools/checkInvestigation`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `missionId` | `string` | 否 | Omit to read the latest investigator mission of this workspace |

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

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

### `checkHunt`

最近一次搜寻或指定搜寻的状态：阶段、找到的人员（附代码的判定和你的判定），以及每项标准的状态及其带日期的公开证据（URL、日期、摘录）。从不包含联系方式。

`POST https://piqline.com/api/v1/tools/checkHunt`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `missionId` | `string` | 否 | Omit to read the latest hunt of this workspace. |

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

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

### `planSourcePack`

针对某个目标，提出一组协调一致的待关注来源。不创建任何内容。

`POST https://piqline.com/api/v1/tools/planSourcePack`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 是 |  |
| `rationale` | `string` | 是 | Why this pack answers the goal |
| `candidates` | `array<object>` | 是 |  |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/planSourcePack \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"texte","rationale":"texte","candidates":[{"platform":"instagram","target":"texte","label":"texte","why":"texte","confidence":"high"}]}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/planSourcePack", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "texte",
    "rationale": "texte",
    "candidates": [
      {
        "platform": "instagram",
        "target": "texte",
        "label": "texte",
        "why": "texte",
        "confidence": "high"
      }
    ]
  }),
});
const { output } = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/planSourcePack",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "name": "texte",
        "rationale": "texte",
        "candidates": [
            {
                "platform": "instagram",
                "target": "texte",
                "label": "texte",
                "why": "texte",
                "confidence": "high",
            },
        ],
    },
)
output = response.json()["output"]
```

### `listWidgets`

可放入此工作区看板的组件，按对用户的相关度排序，并附理由。

`POST https://piqline.com/api/v1/tools/listWidgets`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `period` | `7d \| 30d \| 90d` | 否 | Window used by isProposable. Default 7d. |

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

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

### `getAdvertiserCampaigns`

来自工作区采集的广告主广告档案：广告、在投广告、日期、广告库、国家、已读取的需求、每月新增广告和投放放量、最新广告、信号。从不针对个人。不消耗积分。

`POST https://piqline.com/api/v1/tools/getAdvertiserCampaigns`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `advertiser` | `string` | 是 | Name (or part of it) of the advertiser. |

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

response = requests.post(
    "https://piqline.com/api/v1/tools/getAdvertiserCampaigns",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "advertiser": "texte",
    },
)
output = response.json()["output"]
```

### `listAdSignals`

工作区的广告信号，每小时计算一次：投放开始或停止、放量、新国家、新平台、付费招聘、促销、发布、新广告主。不消耗积分。

`POST https://piqline.com/api/v1/tools/listAdSignals`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `kind` | `ad_campaign_started \| ad_campaign_stopped \| ad_ramp_up \| ad_new_country \| ad_new_platform \| ad_hiring \| ad_promotion \| ad_launch \| …` | 否 | ad_hiring for paid recruitment campaigns, ad_campaign_started for new campaigns, etc. |
| `activeOnly` | `boolean` | 否 |  |
| `limit` | `integer` | 否 |  |

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

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

### `listCollectedAds`

工作区中已读取的广告采集（Meta、TikTok、Google、LinkedIn）：列出采集；若给出采集名称，则返回其细分（角度、优惠、语气、形式）、节奏、投放最久的广告，以及按广告库、状态、角度或关键词筛选的广告。不消耗积分。

`POST https://piqline.com/api/v1/tools/listCollectedAds`

类型：读取。Scope：`read`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `collection` | `string` | 否 | Name of a collection (exact, start or fragment). |
| `library` | `meta \| tiktok \| google \| linkedin` | 否 |  |
| `status` | `live \| new` | 否 | live: active or shown within 14 days. new: first seen at the last pass. |
| `angle` | `promotion \| lancement \| marque \| preuve_sociale \| education \| recrutement \| evenement \| lead \| …` | 否 |  |
| `query` | `string` | 否 | Word to find in the advertiser, title, text, button or transcript. |
| `limit` | `integer` | 否 |  |

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

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