Kleos REST API v1 · beta

Read-only programmatic access to your workspace's Google Ads creative data — the same data behind the app and the AI-assistant connector, for your own scripts and integrations.

Connect an AI assistant

Prefer chatting with your data? Connect Claude Desktop with our one-click desktop extension (in the app: AI assistants → Connect Claude Desktop — download, double-click, sign in once) or ChatGPT via a developer-mode connector with your workspace's MCP endpoint URL. Assistant access is read + stage-only: it can analyze and propose — copy edits, keywords (with per-keyword landing pages), negative keywords (campaign, ad-group, and shared-list audit), geo exclusions, landing-page changes, brand-asset cleanups, even a complete new Search ad group draft — but every proposal lands as a staged change in Kleos. Only you can publish, and anything new is created paused. It never edits or spends on its own.

Authentication

Create a key in the app under AI assistants → API access. Keys are shown once and scoped to your workspace. Send it as a bearer token:

curl -H "Authorization: Bearer kls_your_key_here" \
  https://app.kleosinc.com/api/v1/campaigns

Endpoints

GET /api/v1/account

Account overview — connection health, creative counts, KPI chips.

GET /api/v1/campaigns?date_range=LAST_30_DAYS

Per-campaign performance: spend, ROAS, conversions, conv. value, CPA, CTR. Ranges: TODAY … LAST_MONTH.

GET /api/v1/asset-groups

All live creatives — PMax asset groups and Search RSAs with ad-strength, status, and gap counts.

GET /api/v1/asset-groups/{id}

Full detail for one asset group / RSA: every headline, description, image, and video with per-asset performance and policy status.

GET /api/v1/creative-health

Ad-strength spread, policy issues, idle units, the ranked needs-attention list, fatigue flags.

GET /api/v1/insights

The ranked what's-working / what-to-fix insights snapshot.

GET /api/v1/quadrant?mode=creative|budget

The asset quadrant — per-asset CTR×CVR or per-campaign spend×ROAS, with bucket classification.

Limits & conduct

REST v1 is read-only. Staged writes are available today through the AI-assistant (MCP) connector; REST write endpoints are on the roadmap.
Rate limit: 60 requests/minute per workspace (429 when exceeded — back off and retry).
Data freshness: synced from Google hourly; responses come from the synced store (no live Google quota).
Keys are revocable anytime in-app; every call is logged to your workspace's audit trail.

⚠️ Beta. The v1 surface is stable in shape but may gain fields. Breaking changes will be versioned (v2), never silent — per our roadmap policy.

Questions or needs (more endpoints, webhooks, higher limits)? Tell us — the beta shapes the API.