文档
// 文档

提交 URL

提交一批 URL 进行处理。需要 urls:write 权限和幂等键。

POST /api/v1/urls 接收一批 URL，做校验后为每条被接收的 URL 创建一个任务。接口是幂等的：为每次逻辑请求发送唯一的 Idempotency-Key，重试时平台会回放已存响应。

请求

字段值
方法POST
路径/api/v1/urls
认证Authorization: Bearer shl_live_<key>，需 urls:write scope
必需请求头Idempotency-Key: <唯一字符串，最长 255 字符>
请求体含 urls 数组的 JSON 对象
{
	"urls": [
		"https://example.com/page-a",
		"https://example.com/page-b"
	]
}

限制：单次请求最多 100 条 URL，请求体约不超过 900 KB。

curl -X POST https://shoulu.co/api/v1/urls \
	-H "Authorization: Bearer shl_live_<key>" \
	-H "Idempotency-Key: batch-2026-10-25-001" \
	-H "Content-Type: application/json" \
	-d '{"urls":["https://example.com/page-a"]}'

响应

部分或全部 URL 被接收时返回 202；整批因账单或账号限制失败时返回 429。

{
	"accepted": 1,
	"acceptedTasks": [
		{
			"id": "9b1d…",
			"url": "https://example.com/page-a",
			"status": "pending"
		}
	],
	"rejectedUpfront": [
		{
			"url": "ftp://bad.example",
			"reason": "unsupported_protocol"
		}
	],
	"batchError": null
}
  • accepted 表示平台创建的任务数，不表示上游已受理，也不表示搜索引擎已收录。
  • acceptedTasks[].id 是任务 ID，用 GET /api/v1/tasks/{id} 轮询状态。
  • rejectedUpfront 列出入校时失败的 URL，每条附一个原因。
  • batchError 在整批无法创建任务时给出，取值见 错误与限制。

拒绝原因

reason原因
invalid_url字符串无法解析为 URL
unsupported_protocol仅接受 http: 和 https:
invalid_domain域名未通过校验
blacklisted_domain域名在平台黑名单中
duplicate该账号下相同 URL 已有待处理任务
over_limit校验后批量超出账号上限

幂等

Idempotency-Key 请求头为必填。幂等键按 API 密钥隔离，保留 24 小时。

  • 相同键 + 相同请求体重试：返回已存响应。
  • 相同键 + 不同请求体重试：返回 409 idempotency conflict。
  • 首个请求仍在处理时重试：返回 425，并带 Retry-After: 30。

每批提交使用新键。误用旧键会回放旧响应，而不会创建新任务。