API and MCP

Programmatic access to the same traffic brain.

REST v1 is a read-only API for your synced PPC and SEO data. MCP is the assistant surface for analysis and stage-only proposals. Both are tenant-scoped, rate-limited, and logged to the same audit trail.

Connect an assistant

Use MCP when the AI should reason and stage.

Claude Desktop uses the Traffic Advisor desktop extension. ChatGPT connects through developer-mode connectors. Assistant access can analyze account data and create staged proposals, but cannot publish, enable, or spend.

Traffic Advisor MCP endpoint https://app.kleosinc.com/mcp

Create a workspace access key in the app under Setup -> AI assistants -> API access. Use it as a bearer token or paste it into the Claude Desktop extension.

Claude Desktop extension kleos-adsmcp.mcpb

Available from the app. It bridges Claude Desktop to the hosted MCP endpoint and stores the workspace key in the OS keychain-backed extension field.

Authentication

Workspace keys, shown once.

REST keys start with kls_, are scoped to one workspace, and can be revoked at any time. Send the key as a bearer token.

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

REST v1

Read-only endpoints.

These endpoints read from Traffic Advisor's synced store. They do not call Google live on every request and they do not mutate ad platforms.

GET /api/v1/account

Connection health, creative counts, KPI chips, and workspace summary.

GET /api/v1/campaigns?date_range=LAST_30_DAYS

Per-campaign spend, ROAS, conversions, conversion value, CPA, and CTR from stored daily metrics.

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 or RSA, including headlines, descriptions, images, videos, performance, and policy status.

GET /api/v1/creative-health

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

GET /api/v1/insights

The ranked what's-working and what-to-fix snapshot.

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

Asset or campaign quadrant with learning floors so low-data assets are not mislabeled as losers.

GET /api/v1/seo/overview

SEO target overview: authority, estimated traffic/value, keywords, backlinks, and audit counts.

GET /api/v1/seo/keywords?limit=&sort=

Ranked keywords with position, change, volume, difficulty, estimated traffic, intent, and URL.

GET /api/v1/seo/audit

Latest crawl and audit action items with status and live-verification ledger.

GET /api/v1/traffic/describe

Traffic catalog: sources (Search Console, GA4, Ads, SEO), entities, dimensions, metrics, per-source freshness, research budget

MCP describe_datasets.validation_rules · stage_* → results[rule_id]

Every staged change is validated against a published rule catalog (character limits, slot maximums, policy claims, keyword syntax). A block names its rule; warnings are never dropped; unverifiable-claim blocks can be overridden by a human decision, health claims and Google limits never

MCP jobs · fetch("job:<id>") · page_size / cursor

Calls that exceed their time budget return a job handle instead of a timeout and finish in the background; list tools page with a cursor. One MCP host: app.kleosinc.com/mcp

Calendar & meetings · GET/POST /api/governance/plans · MCP plan_change

Schedule future changes on a real calendar; Kleos emails the .ics invites to up to 3 attendees, reminds 24h before, and updates or cancels automatically when plans change — from the portal or your AI assistant

Fix first · GET /api/recommendations · MCP get_traffic_priorities

One ranked what-to-fix-first queue across ads, SEO, feed, measurement, overdue plans, and measured regressions — real dollars outrank estimates; snooze or dismiss what's intentional; weekly email digest

POST /api/data/export · /api/data/delete · /api/data/delete-me

Your data is yours: export everything as a machine-readable bundle (JSON + Parquet/CSV by month + your original creatives, with a published schema and checksums), delete your workspace with a 30-day grace period and a deletion certificate, or delete just yourself. Google access is revoked at Google the moment you disconnect

GET /api/dashboard/traffic · /api/governance/plans

One traffic overview — paid clicks and spend, exact organic clicks, GA4 sessions and revenue, 28-day deltas and a 90-day series — plus the plan of upcoming changes (add, schedule, prioritise, close) that the home page shows next to what actually changed

MCP list_staged_changes(source=google|all) · GET /api/governance/timeline · /events · /audit

The workspace changelog: every change from every source — your team in Kleos, assistants acting on your behalf (named), Google's own change history with the Google user who made it (web UI, API, rules, auto-apply) — with before/after, plus a tenant-visible audit log of sign-ins, connections, keys and grants. Backfill up to two years of pre-Kleos history from the Google Ads change-history export; the record is yours and portable

MCP stage_status(kind=campaign|ad_group|asset_group|ad|keyword) · stage_final_url_edit(keyword_id) · stage_copy_addition(kind=image)

Pause / enable at every level, keyword landing-page edits, and image assets — all staged for human review, never published by the assistant

MCP get_campaign_performance(start_date, end_date, granularity=daily)

Custom date windows, per-day rows, and Search impression share with budget-lost and rank-lost splits

MCP get_campaign_settings

Campaign status, bidding strategy + targets (tROAS / tCPA / impression share / CPC ceiling), daily budget, merchant link and whether Google auto-apply is on — plus every setting changed outside Kleos, with attribution (auto-apply vs external)

MCP list_staged_changes(source=external) · get_connection_health.sync / .sync_violations

Change history from both sides: what Kleos staged and published, and what changed at Google without Kleos. Per-source sync freshness (ok / failed with the error), and post-sync invariant violations with a remediation. Entities removed at Google are kept as tombstones (include_removed) — an id never silently vanishes

MCP get_connection_health.audit · fetch("audit:datasource")

Data-source configuration audit: 17 checks that each connected source is the right one and that Ads, Search Console, GA4, Merchant Center and DataForSEO agree (hosts, links, scopes, currency, purchase events, coverage)

POST /api/v1/traffic/query

Constrained query over your traffic archives — any slice, with period comparison; zero Google quota

GET /api/v1/traffic/{overlap|reconciliation|priorities}

Computed paid + organic answers: cannibalization, brand bidding, striking distance, SERP coverage, reconciliation, fix-first

POST /api/v1/seo/research

Live DataForSEO research (keyword ideas, keyword gap, competitors, SERP, trends, AI visibility) — budgeted per workspace

POST /api/v1/seo/audit/items/{id}/verify

Re-check an SEO audit item against the live site. The result is verified or reopened.

Limits

Designed for scripts and agents, not scraping.

REST v1 is additive-only during beta. Breaking changes will ship under a new version.

Read-only REST

Staged writes are available through MCP and the app review queue. REST write endpoints are not shipped yet.

60 requests per minute

Rate limit applies per workspace, aligned with MCP tool-call limits.

Audited access

Every API call is logged to the workspace activity trail and visible in the admin observability surfaces.