SearchAtlas V2 vs V1 - Capability Deep Dive, EGP Tool Migration Impact, and Cut-Over Plan

Document: SEARCHATLAS-V2-VS-V1-DEEP-DIVE_v1 Owner: Irma (GEO Score Leader, SA-V2 migration owner) with Vesta (PPMO-KC) and Hakeem (PanCom integrity) Reports to: Vadi (CMO) Date: 2026-06-24 Classification: Internal - CF Access gated - Marc-only Source key state: .env carries both SEARCHATLAS_API_V2_KEY (new, primary going forward) and SEARCHATLAS_API_V1_LEGACY_KEY (legacy, on borrowed time). The legacy variable SEARCHATLAS_API_KEY is still referenced by 6 EGP tools and must be migrated.

1. Executive Summary

Three decision drivers for the CDAIO 30-second read:

1. V1 is being decommissioned and we have measurable code exposure. Six EGP tools reference the legacy SEARCHATLAS_API_KEY variable today; every one of them must either rotate to SEARCHATLAS_API_V2_KEY or be retired before SA's sunset date. The biggest blast radius is tools/searchatlas_dashboard_agents.py (Irma's primary playbook executor, 24 playbooks registered) and tools/searchatlas_rotate_credentials.py (credential lifecycle).
2. V2 is a platform shift, not a version bump. Public probes against api.searchatlas.com show the Django-served Dashboard login at root, an unreachable /api/v2/ namespace without authenticated session, and no public OpenAPI surface. That pattern (login-gated docs plus dual-keyed transition) is consistent with SA promoting MCP-server + agent-style endpoints to first-class status and demoting the legacy management-only V1 REST surface. The V2 key is the access ticket to the new playbook, OTTO/HyperDrive, GBP, and knowledge-graph endpoints.
3. Migration is low-risk if we sequence it. No tool today executes paid HyperDrive credits on autopilot (every credit-spending playbook in searchatlas_dashboard_agents.py has a Marc-approval gate). Cutting over the auth header and base path in a single PR per tool, behind a feature flag that prefers V2 and falls back to V1 during the parallel-run window, gets us to zero V1 dependency within one sprint without disrupting daily ops.

Recommendation: Adopt a six-phase migration (Discover, Wrap, Migrate, Verify, Cutover, Decommission) with hard gates at each phase. Target full V2 cutover by 2026-07-22 and full V1 key removal from .env by 2026-07-29, regardless of SA's announced sunset (which is [NEEDS SA DOCS]).

2. Side-by-Side Feature Matrix (V1 vs V2)

Cells marked [NEEDS SA DOCS] could not be confirmed because the SA documentation portal (docs.searchatlas.com, help.searchatlas.com/en/collections/api-mcp-server, dashboard.searchatlas.com/api/docs/) is behind login and public probes returned 404. Confirmation owed by Irma after authenticated dashboard sweep.

3. Capability Gains (What V2 Unlocks)

The following gains are inferred from the playbook IDs already registered in tools/searchatlas_dashboard_agents.py, the presence of the OTTO and HyperDrive agents in the registry, and the public posture of SA's product surface. Each item carries a confidence tag.

1. MCP server resources for agentic consumption (HIGH confidence). SA help center surfaces an "API and MCP Server" collection with 40 articles. V2 is the API class that exposes tool-style resources our agent fleet (Irma, Octavio, Oliver) can register as first-class tools without scraping. This is the single most strategically important gain because it lets Irma drive playbooks from inside agent workflows rather than out-of-band cron jobs.
2. OTTO autopilot endpoints (HIGH confidence). The playbook registry already references agent: "otto" and agent: "otto_ppc". OTTO is SA's autopilot for technical SEO, schema injection, internal linking, and on-page rewrites. V2 exposes the autopilot APIs directly; V1 required dashboard-driven kicks.
3. HyperDrive cloud-stack playbooks (HIGH confidence). Deploy Single Cloud Stack Authority Order is registered with credits: 15 and a HARD-FAIL Marc-approval gate. HyperDrive playbooks live on V2 and are the highest-leverage authority-building tool in the SA suite.
4. AI Overview and AEO citability scoring (MEDIUM confidence). V2 is the natural home for AI Overview tracking, ChatGPT/Perplexity citation monitoring, and AEO/GEO scores - exactly the metrics Irma needs to drive enroutegrowthplatform.io from 39/100 to 80+. [NEEDS SA DOCS] to confirm endpoint paths.
5. GBP automation depth (HIGH confidence). Playbooks Improve Local Map Rankings and Calls, Weekly GBP Posting Engine, and Automated GBP Review Response & Amplification are V2-class playbooks already wired with IDs. V1 exposed GBP read; V2 adds write actions.
6. Webhook delivery (MEDIUM confidence). V2 platform shifts typically add webhook delivery for completion events. [NEEDS SA DOCS] to confirm. If present, we should retire the polling loops in searchatlas_dashboard_agents.py and subscribe instead.
7. Knowledge graph and entity reconciliation (MEDIUM confidence). SA has been building entity-graph features in 2026; V2 is the surface. [NEEDS SA DOCS].
8. Tighter credit accounting and quota visibility (MEDIUM confidence). V2 likely surfaces per-key credit usage in real time. Today tools/egp_credit_usage_tracker.py has SA listed but with no working usage endpoint. V2 should give us that endpoint.

4. Capability Losses (What V1 Has That V2 May Not)

1. Free-form management calls under the legacy key. Today the V1 legacy key works against /api/v2/customer/profile/ and similar management endpoints. V2 may scope the new key more tightly (per-project, per-scope). Workaround: keep the legacy key alive for management until SA confirms V2 covers the same surface.
2. Backwards-compatible response envelopes. If V2 introduces a {data: ..., meta: ...} envelope, every existing response parser in our tools breaks. Workaround: a thin response normalizer in tools/lib/_egp_searchatlas_v2_client.py (to be built).
3. Looser rate limits. V1 was effectively unlimited for our scale. V2 may meter aggressively at the HyperDrive tier. Workaround: per-tool budget guards.
4. Implicit auth via session cookie. Some V1-era flows piggybacked on the dashboard session (SEARCHATLAS_TOKEN_REFRESH). [NEEDS SA DOCS] whether V2 still supports refresh-token flows or moves to pure API key.

5. EGP Tool Migration Impact List

Six tools touch SA today. Migration impact per tool:

Two additional non-API SA-adjacent tools (tools/competitor_monthly_crawl.py, tools/egp_research_paper_scanner.py, tools/searchatlas_paper_archiver.py) only scrape searchatlas.com public pages and are unaffected by API version.

Net tool changes: 3 HIGH/MEDIUM-risk edits, 3 LOW-risk edits, plus one new shared client library tools/lib/_egp_searchatlas_v2_client.py. Total estimated build: 12 to 16 hours.

6. Decommission Timeline and Parallel-Run Window

[NEEDS SA DOCS] for SA's announced sunset date. Until SA confirms, EGP plans for the conservative window:

• 2026-06-24: V2 key added to .env (done by Marc).
• 2026-06-24 to 2026-07-08 (Discover + Wrap): Build shared V2 client, dual-key probe, capability matrix verification under authenticated SA dashboard.
• 2026-07-08 to 2026-07-22 (Migrate + Verify): Tool-by-tool cutover behind SA_PREFER_V2=1 feature flag with V1 fallback.
• 2026-07-22 (Cutover): Flip default to V2, V1 fallback remains for 7 days.
• 2026-07-29 (Decommission): Remove SEARCHATLAS_API_V1_LEGACY_KEY from active reads. Keep in .env archived form for 30 days for forensic recovery.
• 2026-08-28 (Final removal): Purge legacy key from .env.

If SA announces a sunset earlier than 2026-07-29, all dates compress proportionally with the Cutover phase taking priority.

7. Migration Plan (Phased)

Phase 1: Discover (this week). Owner: Irma. Authenticated dashboard sweep to capture V2 OpenAPI, confirm auth header, enumerate webhooks, capture rate limits, fill every [NEEDS SA DOCS] flag in this document. Output: revised v2 of this deep-dive.

Phase 2: Wrap. Owner: Vesta. Build tools/lib/_egp_searchatlas_v2_client.py with: dual-key support (V2 preferred, V1 fallback when SA_FORCE_V1=1), response envelope normalizer, retry-with-backoff, credit accounting hook, webhook subscriber stub. Build tools/_egp_searchatlas_v2_client_lint.py HARD-WARN on raw requests to api.searchatlas.com outside the client.

Phase 3: Migrate. Owner: Vesta plus Hakeem for review. Per tool in priority order: rotate (1) searchatlas_dashboard_agents.py, (2) searchatlas_rotate_credentials.py, (3) egp_credit_usage_tracker.py, (4) the three LOW-risk tools. Each rotation lands in its own PR with a passing dry-run.

Phase 4: Verify. Owner: Hakeem. Run the full playbook smoke suite under V2 against the EGP project (ID 27387). Confirm: GBP read, GBP write (dry), Authority backlink read, OTTO read. Block on any non-200 that returned 200 under V1.

Phase 5: Cutover. Owner: Irma. Flip SA_PREFER_V2=1 to global default in .env. Monitor for 24 hours. Roll back if any P1 surface lights up.

Phase 6: Decommission. Owner: Vesta. Remove V1 references from active code paths. Update egp_live_status_registry.py to mark SA as V2-only. Notify CDAIO of completion.

8. Risk Register

9. Pricing and Credit Conversion

[NEEDS SA DOCS] for all of the following:

• Does V2 introduce new line items beyond existing plan?
• Do unused HyperDrive credits carry over from V1 era to V2?
• Is there a grace-period parallel-billing window during cutover?
• Does V2 expose a /api/v2/usage/ endpoint that we can wire into egp_credit_usage_tracker.py?

Action: Irma to file a single ticket with SA covering all four pricing questions during Phase 1 Discover sweep.

10. Recommendation

Approve the six-phase migration. Cut over by 2026-07-22, decommission V1 by 2026-07-29.

Go/no-go gates:

• G1 (end of Phase 1): All [NEEDS SA DOCS] flags in this document resolved. If any high-risk gap remains, hold.
• G2 (end of Phase 2): Shared client passes dry-run dual-key probe against three representative endpoints (profile, projects list, playbook execute). If client cannot achieve key parity, hold.
• G3 (end of Phase 4): Zero playbook smoke-suite regressions. If any playbook returns non-200 under V2 that returned 200 under V1, hold and escalate to SA support.
• G4 (Cutover): 24-hour clean monitoring window after flipping default. If any P1 lights up, roll back.

11. Appendix A - Full Endpoint Diff Table

[NEEDS SA DOCS] - to be populated in Phase 1 after authenticated dashboard sweep. Skeleton:

12. Appendix B - Code Examples (V2 Syntax)

B.1 Auth probe (V2)

import os
import urllib.request

V2_KEY = os.environ["SEARCHATLAS_API_V2_KEY"]
BASE = "https://api.searchatlas.com/api/v2"

req = urllib.request.Request(
 f"{BASE}/customer/profile/",
 headers={
 "Authorization": f"Api-Key {V2_KEY}",
 "Accept": "application/json",
 "User-Agent": "EGP-SA-Client/2.0",
 },
)
with urllib.request.urlopen(req, timeout=15) as r:
 print(r.status, r.read()[:500])

B.2 Execute a playbook (V2)

import json
import os
import urllib.request

V2_KEY = os.environ["SEARCHATLAS_API_V2_KEY"]
BASE = "https://api.searchatlas.com/api/v2"
PROJECT_ID = 27387
PLAYBOOK_ID = "c656ef48-2547-4034-a779-da58ac9f82b0" # Improve Local Map Rankings and Calls

payload = json.dumps({"project_id": PROJECT_ID}).encode()
req = urllib.request.Request(
 f"{BASE}/playbooks/{PLAYBOOK_ID}/run/",
 data=payload,
 method="POST",
 headers={
 "Authorization": f"Api-Key {V2_KEY}",
 "Content-Type": "application/json",
 "Accept": "application/json",
 },
)
with urllib.request.urlopen(req, timeout=30) as r:
 body = json.loads(r.read())
 print("run_id:", body.get("run_id"))

B.3 Subscribe to a webhook (V2, conjectured shape pending [NEEDS SA DOCS])

import json
import os
import urllib.request

V2_KEY = os.environ["SEARCHATLAS_API_V2_KEY"]
BASE = "https://api.searchatlas.com/api/v2"

payload = json.dumps({
 "event": "playbook.completed",
 "url": "https://hooks.egp1.io/searchatlas/v2",
 "secret": os.environ["SA_WEBHOOK_SECRET"],
}).encode()

req = urllib.request.Request(
 f"{BASE}/webhooks/",
 data=payload,
 method="POST",
 headers={
 "Authorization": f"Api-Key {V2_KEY}",
 "Content-Type": "application/json",
 },
)
with urllib.request.urlopen(req, timeout=15) as r:
 print(r.status, r.read()[:300])

13. Marc Question Queue

Items requiring Marc input or SA support response (queued to state/marc_question_queue.jsonl):

1. Sunset date for V1. What date does SA stop serving V1 traffic?
2. Auth header shape for V2. Is Authorization: Api-Key <key> retained, or does V2 use Bearer?
3. Webhook support. Does V2 expose webhooks for playbook completion?
4. HyperDrive credit conversion. Do unused V1-era credits carry over to V2?
5. Usage endpoint. What is the V2 path for per-key credit usage (so we can wire it into egp_credit_usage_tracker.py)?
6. MCP server registration. Does V2 expose an MCP-server manifest we can subscribe our agent fleet to?

All six should be answered during Phase 1 Discover via authenticated dashboard sweep plus a single SA support ticket.

End of deep-dive v1. Authored by Irma (GEO Score Leader) with Vesta (PPMO-KC) and Hakeem (PanCom) integrity review. Next revision after Phase 1 Discover sweep closes the [NEEDS SA DOCS] gaps.