快速开始
在 Workspace 中创建 API Key，仅保存一次密钥，然后提交直连优先的抓取请求。
可下载的 OpenAPI 文件是 schema、scope、状态码、分页与示例的机器可读发布契约。
curl --request POST https://toptrends.ai/v1/scrapes \
--header "Authorization: Bearer tt_live_REPLACE_ONCE" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: scrape-2026-08-09-001" \
--data '{
"url": "https://example.com/products",
"mode": "http",
"request": { "method": "GET" },
"output": { "formats": ["markdown", "json"] }
}'核心接口组
POST /v1/scrapesHTTP、Browser 与 Stealth 抓取
POST /v1/batches多网址任务与用量预估
POST /v1/crawls设有边界的站点抓取
GET /v1/jobs状态、结果、用量、取消与重试
GET /v1/artifacts/:id需要认证的制品交付
POST /v1/schedules创建、运行、暂停、恢复与删除
认证与租户隔离
通过 Bearer Token 发送 API Key。每个 Key 只属于一个 Workspace，并具有明确 scope，不能跨租户访问；撤销后立即返回 401。
直连优先执行
HTTP、Browser 与 Stealth 默认使用直连。只有目标确实需要时才添加代理策略；实际代理字节与 credits 会显示在 Job 用量中。
可靠写入
所有创建、取消、重试和 Schedule 变更都应发送 Idempotency-Key。相同载荷会精确重放，不同载荷返回 409。
分页与状态
列表接口使用不透明 cursor。轮询 Job 或消费事件流，直到进入 succeeded、partially_succeeded、failed、cancelled 或 timed_out。
结果与制品
Results 按页返回并按 revision 保持不可变。Artifact 与 Export 提供需认证的下载地址、媒体类型、字节数、校验和与保留信息。
Webhook
Workspace 级 endpoint 会投递带签名、可防重放的 Job 事件。请对原始请求体验证含时间戳签名，并按 event ID 去重。
错误与限制
错误使用 application/problem+json，包含稳定 code 与 request ID。请遵循 Retry-After 和 RateLimit 响应头；参数错误不会入队或扣费。