Skip to main content

Agent API

The versioned HTTP API is served at https://api.spenddaddy.app/api/v1. Its public OpenAPI schema is at /api/v1/openapi.json after deployment. Use an agent key from Settings → Agent API secret keys as an Authorization: Bearer <agent-key> header. Existing keys remain read-only. New keys can have an app allowlist, expiry, and optional mutations capability.

Read endpoints cover apps, bulk keyword lookup, acquisition comparisons, cohort funnel, data health, owner policy, recommendations, and action audit. Acquisition and funnel reads accept inclusive start and end dates up to 365 days. Acquisition and audit lists use cursors; restart pagination if a metrics revision changes.

An owner may enable an app execution policy for four single-target Apple Ads actions: keyword bid, keyword status, campaign daily budget, and campaign status. The policy sets allowed campaigns, action types, expiry, currency, limits, and a daily count. A mutation key alone cannot authorize spend. The organization mutation guardrail is also checked when committing. Configured budget ceilings are not guarantees of actual cash spend.

The preview includes economic evidence and source-quality warnings. Authoritative D30 proceeds may be null when source coverage is unverified; incomplete economics do not block an owner-authorized commit. The preview preserves the evidence the agent saw even if metrics are revised before the commit. Human actions continue through the dashboard.

Preview and retry​

curl -H 'Authorization: Bearer <agent-key>' -H 'Content-Type: application/json' \
  -d '{"type":"keyword_bid","app_id":1,"keyword_id":42,"amount":"1.10","currency":"USD"}' \
  'https://api.spenddaddy.app/api/v1/actions/preview'

curl -H 'Authorization: Bearer <agent-key>' -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <unique-operation-key>' -d '{"preview_id":123}' \
  'https://api.spenddaddy.app/api/v1/actions/commit'

Keep the preview ID and idempotency key. If the response is lost, retry with the same pair; HTTP and MCP share the action audit and return a replay without another Apple Ads write. If an action is pending, call POST /api/v1/actions/{id}/reconcile to read Apple Ads state. Reconciliation never repeats the mutation. An unresolved pending action blocks further agent writes for the app.

Errors have error.code and error.message. Common codes are unauthorized, policy_disabled, preview_expired, snapshot_changed (for pagination), ambiguous_prior_action, and rate_limited. The last includes Retry-After.