Olostep 的 API 是围绕对象设计的。理解这种设计可以帮助你构建更有效的集成。
一切都是对象
Olostep 中的每个资源都是一个具有唯一标识符的对象。无论你通过 API、SDK 还是仪表板创建它，你都会得到一个可以引用、更新和查询的对象。
| 资源 | 对象 ID 格式 | 示例 |
|---|
| Scrape | scrape_* | scrape_abc123 |
| Batch | batch_* | batch_xyz789 |
| Crawl | crawl_* | crawl_def456 |
| Map | map_* | map_ghi012 |
| Answer | answer_* | answer_jkl345 |
| Search | search_* | search_mno678 |
| Monitor | monitor_* | monitor_mno678 |
| File | file_* | file_mno678 |
| Schedule | schedule_* | schedule_pqr901 |
对象可以有生命周期
一些 Olostep 对象通过 status 字段跟踪状态。这种状态机模式让你确切知道每个资源在其生命周期中的位置。
批次有两个级别的状态：批次本身和单个项目。
批次状态：
| 状态 | 描述 |
|---|
in_progress | 正在抓取 URL |
completed | 处理完成 |
批次级别的失败极为罕见。 批次几乎总是完成的——即使某些 URL 失败，批次本身也会达到 completed 状态。在极少数情况下，基础设施出现灾难性故障（例如，在丰富过程中 LLM 服务中断），批次可能会失败。这影响不到 0.01% 的批次。
| 状态 | 描述 |
|---|
success | URL 抓取成功 |
failed | URL 无法抓取 |
- URL 被阻止或返回错误
- 解析器输出缺失
- 网络/获取错误
失败的项目包含一个带有 code 和 message 的 error 对象来解释失败原因。批次仍然会完成——在处理结果时检查每个项目的状态。
| 状态 | 描述 |
|---|
in_progress | 正在积极发现和处理 URL |
completed | 爬网完成 |
爬网总是完成的。 即使爬网找到 0 个 URL（由于 robots.txt 阻止或起始 URL 无效），爬网状态也将是 completed。检查 pages_count 字段以验证结果。
监控器
监控器是具有比一次性资源更丰富生命周期的长寿命对象：
provisioning → active ⇄ paused
↘ failed
| 状态 | 描述 |
|---|
provisioning | 正在设置代理、规格、计划和时间表 |
active | 启用时间表；运行在 schedule.frequency 上执行 |
paused | 通过 POST /v1/monitors/:monitor_id/pause 禁用时间表 |
failed | 设置或时间表更新失败（error_message 已设置） |
deleted | 通过 DELETE /v1/monitors/:monitor_id 软删除 |
202，状态为 provisioning。一旦计划解决其跟踪目标，监控器将变为 active——轮询 GET /v1/monitors/:monitor_id 或使用 ?stream=1 流式传输设置事件。只有 active 的监控器可以暂停，只有 paused 的监控器可以恢复。更新在监控器仍然 provisioning 时返回 409。
检索模式
许多对象生成的内容可以稍后检索。retrieve_id 模式允许你在不重新处理的情况下获取内容。
# 使用 retrieve_id 获取内容
curl "https://api.olostep.com/v1/retrieve?retrieve_id=6h89o8u1kt" \
-H "Authorization: Bearer <your_token>"
- 批次项目 — 每个处理的 URL 都会获得一个
retrieve_id
- 爬网页面 — 每个爬网页面都获得一个
retrieve_id
/v1/retrieve 端点接受 formats 参数以指定返回哪些内容类型（html、markdown、json、text）。
Webhooks：事件驱动的更新
与其轮询状态变化，不如配置 webhooks 以在对象状态更改时接收事件。
{
"event": "batch.completed",
"data": {
"id": "batch_xyz789",
"status": "completed",
"items_total": 100,
"items_completed": 100
}
}
元数据：你的数据与我们的数据一起
使用 metadata 将自定义键值对附加到对象。这让你可以将 Olostep 资源链接到你的内部系统。
{
"items": [{"url": "https://example.com"}],
"metadata": {
"order_id": "12345",
"customer": "acme-corp"
}
}
| 概念 | 描述 |
|---|
| 对象 | 每个资源都有唯一 ID 并且可查询 |
| 生命周期 | 通过 status 字段跟踪进度 |
| 检索 | 使用 retrieve_id 稍后获取内容 |
| Webhooks | 在状态更改时收到通知 |
| 元数据 | 将你自己的数据附加到任何对象 |
