AdsCove

REST API

AdsCove 产品与工程团队 · 最后审核于 2026 年 7 月 10 日

每个 MCP 工具同时也提供对应的 REST 接口，并采用完全相同的身份验证、审批和内部安全规则。适合 n8n、Zapier 和自定义脚本等非 MCP 场景。

身份验证

Authorization: Bearer sk_live_your_key

调用工具

POST https://adscove.com/api/v1/tools/{tool_name}
Content-Type: application/json

{ "limit": 10 }   // tool input params, see Tools Reference

常用写入参数

{
  "execution_mode": "dry_run | auto",   // default dry_run; auto = submit for approval
  "idempotency_key": "unique string, min 8 chars",   // prevents duplicate execution on retry
  "max_budget": 50,
  "currency": "USD"
}

直接上传素材

Codex 在本地生成的图片可以直接上传到已连接平台的素材库。AdsCove 会验证并转发文件，随后丢弃文件内容；日志中只保留平台返回的 ID 和网址。

POST https://adscove.com/api/assets/direct-upload
Authorization: Bearer sk_live_your_key
Content-Type: multipart/form-data

curl -X POST https://adscove.com/api/assets/direct-upload \
  -H "Authorization: Bearer sk_live_your_key" \
  -F "execution_mode=dry_run" \
  -F "platforms=meta,google,shopify" \
  -F "file=@/absolute/path/to/image.png"

curl -X POST https://adscove.com/api/assets/direct-upload \
  -H "Authorization: Bearer sk_live_your_key" \
  -F "confirmed=true" \
  -F "platforms=meta,google,shopify" \
  -F "file=@/absolute/path/to/image.png" \
  -F "asset_name=Product angle - square"

状态码

200成功，包括预览成功
202已进入审批队列
400参数无效、工具执行失败或触发安全规则
401API 密钥无效或已撤销
402需要升级套餐或达到内部安全上限
403只读密钥、安全规则拦截或平台授权问题
429AdsCove 或平台触发请求频率限制
501工具已列出，但执行能力尚未开放
503已连接平台暂时不可用

返回数据格式

{
  "status": "success | pending_approval | failed | quota_exceeded",
  "tool_name": "shopify_list_products",
  "execution_id": "uuid",          // audit-log ID, searchable on the console Activity page
  "internal_units": 1,             // internal protection counter, not a customer bill
  "cached": false,                 // true on an idempotency hit
  "data": { ... },
  "error": {
    "code": "not_connected",
    "message": "Connect google in AdsCove before calling google_list_campaigns.",
    "category": "connection",
    "retryable": false,
    "user_action": "Connect the required platform account in AdsCove Connections, then retry.",
    "operator_action": "Check platform_connections and platform_tokens for the user.",
    "platform": "google"
  }
}

根据错误代码解决问题

智能体应先判断 error.code，再根据 retryable 和 user_action 选择下一步；message 字段用于说明这次失败的具体原因。

not_connected / token_missing / not_enabled
→ 请用户连接、重新连接或启用对应平台账户。

ambiguous_connection
→ 调用 list_connections，再带上 account_id 或 connection_id 重试。

invalid_input / platform_validation_failed / missing_assets
→ 修正请求字段或补齐所需素材后再重试。

plan_upgrade_required / read_only_key
→ 使用有权限的工具或密钥，或引导用户升级。

rate_limited / platform_rate_limited / platform_unavailable
→ 只有 retryable 为 true 时，才在稍后重试。

policy_violation
→ 修改请求，不要重复提交被拦截的内容。

capability_not_implemented
→ 不要当作成功；请使用其他已开放工具或联系 AdsCove。