API and MCP

Send a 6-digit code and magic link (rate-limited).

Body

{ email, turnstile_token, next? }

Returns

{ ok: true }

Exchange the code for a session cookie.

Body

{ email, code }

Returns

{ user, accounts, account_id }

Magic link: sets the cookie and resumes a safe internal path, or the workspace/onboarding.

Clear the session cookie.

Current session or 401.

Returns

{ user, accounts, account_id }

Accept an invite after signing in.

Body

{ token }

MCP resource discovery.

Issuer, endpoints, scopes and public-client registration.

Register a client with HTTPS or native loopback redirects.

Body

{ client_name, redirect_uris, token_endpoint_auth_method: "none" }

Sign in, select a workspace and consent. Requires response_type=code, client_id, redirect_uri, resource, S256 challenge; scope/state optional.

Code + verifier exchange or refresh-token rotation. client_id and resource required.

Revoke a connection using token and matching client_id.

Signed-in browser: inspect and revoke your connections.

User, workspaces and the selected workspace.

Create a workspace; the creator is owner.

Body

{ name, timezone? }

Rename, timezone, ready-by hour of the daily scan (admin+).

Body

{ name?, timezone?, scan_hour? }

Delete the workspace and all its data (owner, signed-in session). Cascades; audit-logged.

Body

{ confirm: <workspace slug> } → { ok, deleted, account_id, apps, members }

Set the session's default workspace.

Members with roles.

Change a role.

Body

{ role }

Remove a member (owner only for owners).

Invite by email.

Body

{ email, role }

Pending and accepted invites.

Revoke an invite.

Key metadata (never the key).

Create a key; admin requires write scope and a signed-in admin/owner. The full key is returned once.

Body

{ name, scope, admin?: boolean }

Returns

{ key: "srk_…", …meta }

Revoke a key.

Apple Ads connection status and last sync.

Save credentials; the .p8 PEM is encrypted at rest.

Body

{ client_id, team_id, key_id, org_id, private_key_pem, enabled }

Request a token and list campaigns.

Returns

{ ok, message }

Delete credentials.

Start an Apple Ads sync.

Returns

{ queued: true }

Every supported storefront (public, cached 1 day). Store codes in app and keyword writes must come from this list.

Returns

[{ code, name, flag, language, region }]

Resolve a store URL or ID to listing details and keyword suggestions.

App Store autocomplete.

Returns

{ terms: [...] }

Apps with health, visibility and the top digest item.

Add an app with keywords; queues a manual scan.

Body

{ name, apple_id?, google_package?, primary_store, stores[], keywords[], result_limit? }

Full app: settings, counts, health, Apple Ads state.

Update identifiers, markets, depth, settings. Validates settings.profile with field-level errors; unknown store codes → 400 naming the code.

Delete an app and its data (owner/admin).

Queue a manual scan. 409 if one ran within the hour.

Returns

{ run_id, queued_jobs, eta_seconds }

Scan runs with error text.

Health row plus lane queue stats.

Keyword configuration with excluded_pairs and effective_pairs.

Ensure keyword scopes; existing markets are kept.

Body

{ items: [{ term, stores?, platforms?, is_brand?, note?, source? }] }

Returns

{ created, extended, unchanged, skipped, items }

Ensure 1–500 keyword scopes, returning added/effective pairs per item.

Body

{ items: [{term, stores, platforms, is_brand?, note?, source?}] }

Returns

{ created, extended, unchanged, skipped, items }

Active, brand, note; replacing markets/platforms requires replace: true.

Delete a keyword.

Bulk scope/flag changes, pair pause/resume, or delete. Preview with dry_run: true.

Body

{ ids, add_stores?, remove_stores?, add_platforms?, remove_platforms?, pause_pairs?, resume_pairs?, set?: {is_active?, is_brand?}, delete?, dry_run? }

The keyword table: one row per keyword, platform and market.

Ranks, popularity, paid, latest SERP and coverage.

CSV export of the keyword table.

Digest items, newest first.

Growth actions with evidence and gate status: open is ready (gate passed), waiting has not passed yet. The first page adds 30-day quality.

Returns

{ items, total, limit, offset, has_more, quality?: { window_days, queue, decisions, precision, premature_rate, repeats, missed } }

Mark done, dismissed, snoozed or open, with an optional typed reason. Reopening an action whose gate has not passed returns it to waiting.

Body

{ state, reason?, reason_code?: wrong_intent|wrong_market|insufficient_evidence|not_useful (dismissed) | already_done (done) }

Keyword ideas with intent, source, key and dismissal reason. New is the review queue; research keeps weaker candidates with evidence.admission.reasons.

Ensure the idea platform/store pair before marking tracked; returns the ensure result.

Body

{ stores?, platforms? }

Dismiss an idea; default reason manual. no_demand and not_useful come back when the evidence changes; wrong_intent also labels it excluded.

Body

{ reason?, reason_code?: wrong_intent|wrong_market|no_demand|duplicate|not_useful }

Label 1–500 keywords or ideas; sessions default to manual, API keys to agent.

Body

{ items: [{ keyword_id? | idea_id?, intent, key?, source? }] }

Returns

{ items: [{ keyword_id? | idea_id?, result, intent?, intent_source?, intent_key? }] }

Reopen a dismissed idea with manual source; excluded becomes unknown.

Set direct/adjacent/excluded role; null clears to discovered.

Body

{ platform, role, reason? }

Visibility series, markets, movers, data quality. Without store (or store=all) every market is combined; without platform every platform.

Competitors by share of search, with role and reason.

Competitor detail.

Discover a competitor's keywords in the given markets: candidates from their localized listing, autocomplete, Apple Ads popularity and your tracked terms, verified with search-result scans. 409 within 24 h for the same competitor and market; cap × markets ≤ 1,000 jobs.

Body

{ platform, stores[], cap? }

Returns

{ run_id, run_ids, queued_jobs, eta_seconds, reused_snapshots }

Their verified keywords per market with their rank, your rank, tracked flag, popularity, sources and gap score, plus run progress.

Terms where competitors reach the top 10 and you are unranked or not tracking the market, scored by popularity × 1/rank × role.

Live listing, locales, draft, coverage and change log.

Save the workspace draft for a market.

Log a manual ledger entry.

Body

{ field, old_value, new_value, observed_at, note }

Experiments. POST to create, PATCH /:eid to end.

Spend, installs, CPI, waste, winners, negatives, target CPA, locales.

Paid search terms, aggregated.

Impression share per term.

Apple's curated genre term list.

Benchmark rows per app and platform.

Workspace-wide digest across apps: what changed since a day.

OpenAPI spec.

Service health and the deployed git SHA.