REST API

AdsCove Product & Engineering · Last reviewed July 10, 2026

Every MCP tool is also available as a REST endpoint with the same authentication, approval, and internal safety rules. This is useful for non-MCP workflows such as n8n, Zapier, and custom scripts.

Authentication

Authorization: Bearer sk_live_your_key

Call a tool

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

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

Common write parameters

{
  "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"
}

Direct asset upload

Images generated locally by Codex can be uploaded directly to connected platform asset libraries. AdsCove validates and forwards the file, then discards the bytes. Only platform IDs and URLs are returned and logged.

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"

Status codes

200	Success, including preview success
202	Entered the approval queue
400	Invalid parameters, tool execution failed, or policy block
401	API key is invalid or revoked
402	Plan upgrade required or internal safety limit reached
403	Read-only key, policy block, or platform authorization issue
429	AdsCove or the platform applied a rate limit
501	Tool is listed but the live executor is not available yet
503	Connected platform is temporarily unavailable

Response shape

{
  "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"
  }
}

Resolve errors by code

Agents should check error.code first, then use retryable and user_action to choose the next step. The message field provides readable details about the specific failure.

not_connected / token_missing / not_enabled
→ Ask the user to connect, reconnect, or enable the platform account.

ambiguous_connection
→ Call list_connections, then retry with account_id or connection_id.

invalid_input / platform_validation_failed / missing_assets
→ Fix request fields or upload required assets before retrying.

plan_upgrade_required / read_only_key
→ Use a permitted tool or key, or direct the user to upgrade.

rate_limited / platform_rate_limited / platform_unavailable
→ Retry later only when retryable is true.

policy_violation
→ Change the request; do not retry the blocked input.

capability_not_implemented
→ Do not treat this as success. Use another available tool or contact AdsCove.