## 查询取数接入路线

以下是推荐阅读顺序，不代表已完成的进度；可选步骤可以跳过。

1. [获取与使用 API Key](/docs/authentication)
2. [完成第一次查询](/docs/quickstart) ← 当前页
3. [关键词与语义检索](/docs/search)
4. [用户、话题、标签与分类](/docs/browse)（可选）
5. [读取内容与历史](/docs/documents)
6. [下载图片与附件](/docs/attachments)（可选）
7. [限流、重试与排错](/docs/production)

**开始前**：已配置 Consumer API Key，准备 Bash、curl 和 jq。

# 完成第一次查询

完成本页后，你将使用平台分配给接入应用的订阅和应用密钥执行一次关键词检索。

## 接入前提

1. 平台已为你的组织开通 Portal 账号。
2. 组织下已有接入应用。
3. 平台已给该应用分配有效订阅。
4. 组织 owner/admin 已在 Portal「接入应用 → 应用密钥」创建 Consumer API Key，并安全交付给你。
5. 本机有 Bash、curl（支持 `--fail-with-body`）和 jq。

本页只查询已有数据，不发起新采集。

生产 Base URL：


```text
https://www.marsyoo.com
```


## 第一次查询


```bash
export WHALE_BASE_URL="${WHALE_BASE_URL:-https://www.marsyoo.com}"
: "${WHALE_API_KEY:?Set the Consumer API Key from Portal}"

search_response="$(curl -sS --fail-with-body --request POST "$WHALE_BASE_URL/v1/search" \
  --header "Authorization: Bearer $WHALE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "mode": "keyword",
    "query": "人工智能",
    "limit": 10
  }')"
printf '%s' "$search_response" | jq .
DOCUMENT_ID="$(printf '%s' "$search_response" | jq -r '.results[0].document_id // empty')"
```


响应结构（字段完整说明见[关键词与语义检索](/docs/search)）：


```json
{
  "mode": "keyword",
  "results": [
    {
      "document_id": "doc_01J...",
      "source_platform": "weibo",
      "title": "...",
      "body": "最佳命中分块摘要",
      "score": 0.87,
      "published_at": "2026-09-10T12:00:00Z"
    }
  ],
  "total": 342,
  "cursor": "eyJv..."
}
```


验证：请求成功，响应有 `results` 数组。`results=[]` 仍可能是正常结果，先确认关键词、已有数据和订阅范围，不要因此自动发起实时采集。

本例不传平台过滤，使用应用已有的授权范围。需要限定平台时，添加合法的 `platforms` 枚举；过滤不能扩大订阅权限。`/v1/contents/search` 是旧兼容入口，新接入使用 `/v1/search`。

## 读取详情

只有结果非空才执行下一步；这里使用上一步自动取得的 `document_id`：


```bash
: "${DOCUMENT_ID:?No matches; check the query and subscription before reading details}"
curl -sS --fail-with-body "$WHALE_BASE_URL/v1/documents/$DOCUMENT_ID" \
  --header "Authorization: Bearer $WHALE_API_KEY"
```


返回文档元数据和当前版本信息；字段说明见[读取内容与历史](/docs/documents)。

完整正文：


```bash
curl -sS --fail-with-body "$WHALE_BASE_URL/v1/documents/$DOCUMENT_ID/content" \
  --header "Authorization: Bearer $WHALE_API_KEY"
```


## 请求失败时

`401` 查 Key 是否有效；`403` 查订阅和字段权限；`429` 按限流策略退避。错误处理见[限流、重试与排错](/docs/production)。不要把 Key 放进日志或 Agent 对话。

查询和正文读取成功后，进入[关键词与语义检索](/docs/search)，选择适合实际需求的检索模式与筛选条件。

## 检查与继续

**完成标准**：查询得到 document_id，并成功读取对应正文；空结果时先检查关键词和订阅，不自动发起采集。

上一步：[获取与使用 API Key](/docs/authentication)

**推荐下一步**：[关键词与语义检索](/docs/search)