REST API 概览

REST API 位于 https://www.renewsell.com/v1，用 API 密钥认证，请求和响应都是 JSON。这一页列出全部资源和端点，以及分页、错误和幂等的规则。

认证

每个请求带一个 API 密钥，两种写法都可以：

curl "https://www.renewsell.com/v1/credits" \
  -H "Authorization: Bearer $RENEWSELL_API_KEY"

curl "https://www.renewsell.com/v1/credits" \
  -H "x-api-key: $RENEWSELL_API_KEY"

密钥在 API 密钥 页面创建，见 API 密钥。密钥是一串 64 个字母，没有固定前缀。缺少密钥返回 401，密钥没有对应权限返回 403。

资源与端点

资源	端点
目标客户	GET、POST /v1/targets；GET、PATCH、DELETE /v1/targets/{target}
启动与扩容	POST /v1/targets/{target}/start、/cancel、/expand；GET、PATCH /v1/targets/{target}/sourcing
条目	GET /v1/targets/{target}/items；GET、DELETE /v1/targets/{target}/items/{id}；POST /v1/targets/{target}/items/{item}/enrichments/{enrichment}/retry
搜索	POST /v1/targets/{target}/searches；GET /v1/targets/{target}/searches/{id}；POST /v1/targets/{target}/searches/{id}/cancel
信息富集列	POST、GET /v1/targets/{target}/enrichments；GET、PATCH、DELETE /v1/targets/{target}/enrichments/{id}；POST …/{id}/cancel、…/{id}/retry
事件	GET /v1/events、GET /v1/events/{id}
Webhook	POST、GET /v1/webhooks；GET、PATCH、DELETE /v1/webhooks/{id}；GET /v1/webhooks/{id}/attempts
监控	POST、GET /v1/monitors；GET、PATCH、DELETE /v1/monitors/{id}；GET /v1/monitors/{monitor}/runs、/runs/{id}
导入	POST、GET /v1/imports；GET、PATCH、DELETE /v1/imports/{id}；PUT /v1/imports/{id}/upload?token=…
额度	GET /v1/credits
任务	GET /v1/jobs/{id}；POST /v1/jobs/{id}/cancel
已连接渠道	GET /v1/connect/accounts
海关数据	POST /v1/customs/{operation}，7 个操作见 海关数据

完整的机器可读描述发布在 /openapi.json（OpenAPI 3.1）。

几个约定：

• {target} 可以是目标客户 id，也可以是创建时给的 externalId。
• id（包括目标客户 id）都是不透明字符串，不要根据前缀或长度推断含义。
• GET /v1/targets/{target}?expand=items 会在响应里带上前 100 条条目。
• POST /v1/targets 默认创建后立即开始查找；带 "start": false 只建草稿，之后用 POST /v1/targets/{target}/start 启动。
• 导入先 POST /v1/imports 拿到 uploadUrl，再把 CSV PUT 到那个地址；上传用签名 token，不需要 API 密钥。
• GET /v1/credits 返回套餐、间隔、可用额度、已预留、每月额度和本期用量。

分页

列表返回统一的结构：

{
  "data": [],
  "hasMore": false,
  "nextCursor": null
}

用 limit 和 cursor 翻页。默认值和上限：

列表	默认	上限
目标客户	25	100
条目	20	100
事件	25	200
Webhook、监控、导入、投递记录	25	200

nextCursor 是不透明字符串，只在同一个列表、同一个账号、同样的过滤条件下有效；不要跨列表复用。

错误

失败时返回 HTTP 状态码和统一结构：

{ "error": { "code": "not_found", "message": "Resource not found" } }

状态码	code	含义
400	invalid_request	参数或请求体不合法
401	unauthorized	密钥缺失或无效
402	insufficient_credits	额度不足
403	forbidden	密钥没有这个操作需要的权限
404	not_found	资源不存在，或不属于这个账号
409	conflict	当前状态不允许这次操作
429	rate_limited	请求过快，按 Retry-After 等待
500	internal_error	服务端错误
502	上游错误码	外部数据源出错
503	provider_unavailable、service_unavailable	这项能力当前不可用
504	timeout	请求超时

每个响应都带 X-Request-Id。反馈问题时附上它，可以直接定位这一次请求。

幂等

海关数据的计费操作必须带 Idempotency-Key 请求头；用同一个 key 重试不会重复扣费。其他写操作没有幂等键，超时后不要直接重试，先查询资源状态再决定。

示例

export RENEWSELL_API_KEY="your-api-key"

curl "https://www.renewsell.com/v1/targets?limit=10" \
  -H "Authorization: Bearer $RENEWSELL_API_KEY"

响应节选：

{
  "data": [
    {
      "id": "…",
      "object": "target",
      "status": "idle",
      "title": "German outdoor furniture importers",
      "createdAt": "2026-10-20T09:15:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

相关

• API 密钥
• Webhooks
• 海关数据
• 额度如何计算