---
title: "AI Read API & Markdown 接口文档"
source: "https://llmo.com.cn/docs/api.md"
---

# AI Read API & Markdown 接口文档

> 供开发者、CLI 工具与编码 Agent 使用。查询已知站点时请优先读取公开 Markdown 档案（零限流、秒级返回）；需要实时重测目标网站时再调用检测 API。

## 1. 首选方案：直接读取公开档案与内容协商（零配额消耗）

1. **直接访问 `.md` 镜像**：
   - 单站报告：`GET https://llmo.com.cn/sites/{host}.md`
   - 全站索引：`GET https://llmo.com.cn/sites.md`
   - 行业目录：`GET https://llmo.com.cn/sites/industry/{slug}.md`（支持 `cross-border-dtc`、`ecom-saas`、`b2b-saas`）
   - 若目标站点尚未收录公开，返回 `404`；若已撤下，返回 `410`。
2. **HTTP 内容协商（RFC 9110）**：
   - 请求 HTML URL 并携带 `Accept: text/markdown`（或 `Accept: text/markdown, text/html;q=0.8`），服务端会原地返回 `200 text/markdown; charset=utf-8`（无 307 重定向）及 `Vary: Accept`。
   - 支持协商的路径：`/`（返回 `/llms.txt`）、`/how-it-works`、`/docs/api`、`/playbooks/diagnose-and-fix`、`/articles/{slug}`、`/sites`、`/sites/industry/{slug}`、`/sites/{host}`。
3. **JSON 目录接口**：
   - `GET https://llmo.com.cn/api/v1/sites` -> 返回 `{ "items": [...], "count": N }`
   - `GET https://llmo.com.cn/api/v1/sites/{host}` -> 返回完整公开快照 JSON（未公开 `404`，已撤下 `410`）

## 2. 实时单页检测 API

### 2.1 创建或命中缓存检测：`POST /api/v1/scans`

请求头：`Content-Type: application/json`
请求体：

```json
{
  "url": "https://example.com",
  "force": false
}
```

- `url`（必填）：待检测页面的 `http://` 或 `https://` 地址（仅允许 80/443 端口；禁止内网/回环 IP 与本地保留域名）。
- `force`（可选，默认 `false`）：是否跳过结果缓存强制重测。

响应：
- **`200 OK`（缓存命中，TTL 600 秒）**：直接返回完整的 `ScanResult` JSON（含 `cached: true`），无需再连 SSE。
- **`202 Accepted`（新建异步扫描，超时硬上限 20 秒）**：

```json
{
  "scan_id": "sc_...",
  "status": "queued",
  "events_url": "/api/v1/scans/sc_.../events"
}
```

### 2.2 订阅检测进度（SSE）：`GET /api/v1/scans/{scan_id}/events`

- 返回 `text/event-stream`，支持断线携带 `Last-Event-ID` 补发事件，不重放、不跳过。
- 事件依次覆盖阶段进展，直到收到 `scan_completed` 或 `scan_failed` 后关闭流（对不存在的 `scan_id` 最长等待 60 秒后发送失败收尾）。

### 2.3 获取完整检测结果：`GET /api/v1/scans/{scan_id}`

- 在收到 `scan_completed` 后请求此端点，获取完整 `ScanResult` JSON。
- 结果在 Redis 中保留 **600 秒**，过期后返回 `404`。

## 3. 同源多页抽样 API：`POST /api/v1/site-sample`

仅在需要排查首页之外的关键路径（如 `/pricing`、`/products`、文档与分类页）时调用。该接口为**同步阻塞请求**（最长 **40 秒**）：

```json
{
  "url": "https://example.com",
  "pages": 12,
  "force": false
}
```

- `pages`：可选，范围 `1–20`，默认 `12`。
- 同一目标站每 24 小时最多抽样 **3 次**，缓存 **600 秒**，仅抓取同主机页面。

## 4. 频率限制与错误响应

- **用户侧限流**：单 IP 每分钟最多 **10 次**扫描/抽样请求；同一目标域名每分钟最多 **5 次**。
- **目标站保护**：同一目标域名全局并发上限 **2**、日配额 **200 次**；单次检测向目标站发起约 11 个 HTTP 请求，不绕过 WAF/验证码，遵守 8 秒单次请求上限与 SSRF 白名单拦截。
- **统一错误结构**（HTTP `400` / `404` / `410` / `429` / `503`）：

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "请求太频繁了，请稍后再试"
  }
}
```

## 5. 相关文档

- [导航索引 /llms.txt](https://llmo.com.cn/llms.txt): 遵循 llms.txt 规范的轻量站点与文档导航清单（< 8KB）。
- [全量合集 /llms-full.txt](https://llmo.com.cn/llms-full.txt): 动态聚合全量说明端点（约 35KB），汇集方法、API、Playbook、实测报告与公开站档案摘要。
- [诊断与修复 Playbook](https://llmo.com.cn/playbooks/diagnose-and-fix.md)
- [Agent Skill 定义](https://llmo.com.cn/skills/ai-read/SKILL.md)
