Apinoa Docs

Feedback API

报告失败的调用、错误或缺失的数据,或者申请我们还没有的 API。免费,有没有 API 密钥都可以;用报告的 id 查看我们的回复。

查看原始 .mdx
POST /v1/feedback
GET  /v1/feedback/{id}

当调用失败、返回的值不对、页面上有的内容响应里没有,或者你需要的平台、操作或选项不存在时,请告诉我们。它是免费的, 不需要 API 密钥也能发送,所以 AI 代理可以在遇到问题的那一刻就发出。带上你的密钥,报告会关联到你的账户, 我们就能查看你在 requestId 中指明的那次调用。

每个报告都有一个 id。它的状态和我们的回复在 GET /v1/feedback/{id}。在 contact 中提供邮箱地址,或者带上 密钥发送,回复也会通过邮件发给你。

发送反馈

curl -X POST "https://gateway.apinoa.com/v1/feedback" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "wrong_data",
    "message": "price is the list price, not the sale price shown on the page",
    "platform": "amazon",
    "operation": "product",
    "params": { "asin": "B0CX23V2ZK" },
    "requestId": "43d899616f8e468aa22368bffaae1953",
    "received": "\"price\": { \"amount\": 29.99 }",
    "expected": "24.99",
    "contact": "dev@example.com"
  }'

参数

请求头

请求头必填说明
Content-Typeapplication/json。
x-api-key你的 API 密钥,用于将报告关联到你的账户。省略则匿名发送;如果发送了密钥,它必须有效。

请求体:最大 64 KB 的 JSON 对象。

字段类型必填说明
typestring是下列类型之一。
messagestring是用你自己的话说明发生了什么,或你需要什么。最多 4,000 个字符。
platformstring路径中的平台名:amazon、tiktok、google…
operationstring路径中的操作名:search、product、posts…
paramsobject你发送的参数。最大 8 KB。
requestIdstring你要报告的那个响应的 requestId。与密钥一起发送时,我们可以查看那次调用。
urlstring显示正确数据的页面,或报告所涉及的条目。
receivedany响应中有误的部分:文本,或原样的 JSON 值。最大 16 KB。
expectedany本应得到的内容:文本或 JSON 值。最多 4,000 个字符。
contactstring接收我们回复的邮箱地址。
sourcestring发送方,例如你的代理或应用的名称。最多 32 个字符。
type适用情况请附上
error调用失败或行为异常。platform、operation、params、requestId,以及收到的错误(放在 received)。
wrong_data某个字段的值不对。同上,再加上 expected,或显示正确值的 url。
missing_data页面上显示的内容不在响应里。同上,以及该页面的 url。
feature_request你需要我们还没有的平台、操作、字段或选项。在 message 中说明你想怎么调用、想得到什么。
other其他任何情况。

响应

新报告返回 201 Created:

{
  "success": true,
  "data": {
    "id": "fb_6f1c2a9e0b4d4e7f8a3b5c1d2e9f0a7b",
    "status": "received",
    "createdAt": "2026-11-11T10:00:00Z"
  }
}

一天之内用同一个密钥(没有密钥时,来自同一发送方)再次发送相同的 type 和 message,不会新建报告,而是以 200 OK 返回第一个报告。

查看状态和回复

curl "https://gateway.apinoa.com/v1/feedback/fb_6f1c2a9e0b4d4e7f8a3b5c1d2e9f0a7b"

不需要密钥,有 id 即可。不会返回你发送的内容,只返回我们这一侧的状态和回复:

{
  "success": true,
  "data": {
    "id": "fb_6f1c2a9e0b4d4e7f8a3b5c1d2e9f0a7b",
    "type": "wrong_data",
    "status": "resolved",
    "reply": "Fixed: product now returns the sale price. Retry the call.",
    "repliedAt": "2026-11-12T08:30:00Z",
    "createdAt": "2026-11-11T10:00:00Z",
    "updatedAt": "2026-11-12T08:30:00Z"
  }
}
字段类型含义
statusstringreceived,处理中为 in_progress,之后为 resolved 或 declined。
replystring | null我们的回复;回复之前为 null。
repliedAtstring | null回复的时间。
createdAt, updatedAtstring报告到达的时间和最后一次变更的时间。

SDK 和 MCP

  • TypeScript:client.feedback.send({ type, message, ... }) 和 client.feedback.get({ id })。要不带密钥 发送,请用 new ApinoaClient({ auth: false }) 创建客户端。
  • Python:client.feedback.send(type=..., message=..., request_id=...) 和 client.feedback.get(id)。
  • MCP:send_feedback 和 get_feedback 工具。不需要密钥。

错误

状态代码含义
400BAD_REQUEST请求体不是带有 type 和 message 的 JSON 对象,或某个字段无效;错误信息会指出是哪个字段。
401UNAUTHORIZED发送了 x-api-key,但密钥无效或已撤销。要不带密钥发送,请去掉该请求头。
404NOT_FOUND没有此 id 的反馈。
413PAYLOAD_TOO_LARGE请求体超过 64 KB。
429RATE_LIMITED同一发送方的报告太多。请等待 Retry-After 秒。
503SERVICE_UNAVAILABLE暂时无法保存报告,请稍后重试。

限制和价格

  • 免费。 无论是否带密钥,反馈都不计费。
  • 频率。 不带密钥时,同一发送方每小时 10 个、每天 50 个;带密钥时,每个密钥每小时 30 个。不带密钥时, 在繁忙时段可能更早收到 429;带密钥发送的报告不受影响。
  • 我们保留的内容。 报告以及你提供的邮箱地址会被保留,以便我们回复并修复你报告的问题。参见 隐私政策。

本页内容