@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/radar.md

@@ -0,0 +1,1431 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.radar`: Radar
+
+42 operations (27 read, 1 destructive, 13 billable, 1 external).
+
+No hand-written client covers this area. Call it through `g8.api.radar.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [radar.d.ts](radar.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`aeoOverview`](#op-aeooverview) | `GET /api/v1/radar/aeo` | read | `radar:read` | Aeo Overview |
+| [`aeoProbes`](#op-aeoprobes) | `GET /api/v1/radar/aeo/probes` | read | `radar:read` | Aeo Probes |
+| [`aeoRun`](#op-aeorun) | `POST /api/v1/radar/aeo/run` | billable | `radar:run` | Aeo Run |
+| [`analyzeGaps`](#op-analyzegaps) | `POST /api/v1/radar/gaps/analyze` | billable | `radar:run` | Analyze Gaps |
+| [`approveAllOpportunities`](#op-approveallopportunities) | `POST /api/v1/radar/opportunities/approve-all` | billable | `radar:write` | Approve All Opportunities |
+| [`approveOpportunity`](#op-approveopportunity) | `POST /api/v1/radar/opportunities/{gap_id}/approve` | billable | `radar:write` | Approve Opportunity |
+| [`bulkAddCompetitors`](#op-bulkaddcompetitors) | `POST /api/v1/radar/competitors/bulk` | billable | `radar:write` | Bulk Add Competitors |
+| [`compareSnapshot`](#op-comparesnapshot) | `GET /api/v1/radar/snapshots/{snapshot_id}/compare` | read | `radar:read` | Compare Snapshot |
+| [`competitorBattleCard`](#op-competitorbattlecard) | `GET /api/v1/radar/competitors/{competitor_id}/battle-card` | read | `radar:read` | Competitor Battle Card |
+| [`competitorSuggestions`](#op-competitorsuggestions) | `GET /api/v1/radar/competitors/suggestions` | read | `radar:read` | Competitor Suggestions |
+| [`createCompetitor`](#op-createcompetitor) | `POST /api/v1/radar/competitors` | billable | `radar:write` | Create Competitor |
+| [`deleteCompetitor`](#op-deletecompetitor) | `DELETE /api/v1/radar/competitors/{competitor_id}` | destructive | `radar:delete` | Delete Competitor |
+| [`discoverCompetitorPages`](#op-discovercompetitorpages) | `GET /api/v1/radar/competitors/{competitor_id}/discover-pages` | billable | `radar:run` | Discover Competitor Pages |
+| [`dispatchAlerts`](#op-dispatchalerts) | `POST /api/v1/radar/alerts/dispatch` | external | `radar:run` | Dispatch Alerts |
+| [`featureMatrix`](#op-featurematrix) | `GET /api/v1/radar/feature-matrix` | read | `radar:read` | Feature Matrix |
+| [`getCompetitor`](#op-getcompetitor) | `GET /api/v1/radar/competitors/{competitor_id}` | read | `radar:read` | Get Competitor |
+| [`getCompetitorAds`](#op-getcompetitorads) | `GET /api/v1/radar/competitors/{competitor_id}/ads` | read | `radar:read` | Get Competitor Ads |
+| [`getCompetitorEngagers`](#op-getcompetitorengagers) | `GET /api/v1/radar/competitors/{competitor_id}/engagers` | read | `radar:read` | Get Competitor Engagers |
+| [`getCompetitorPages`](#op-getcompetitorpages) | `GET /api/v1/radar/competitors/{competitor_id}/pages` | read | `radar:read` | Get Competitor Pages |
+| [`getCompetitorPosts`](#op-getcompetitorposts) | `GET /api/v1/radar/competitors/{competitor_id}/posts` | read | `radar:read` | Get Competitor Posts |
+| [`getCompetitorTraffic`](#op-getcompetitortraffic) | `GET /api/v1/radar/competitors/{competitor_id}/traffic` | read | `radar:read` | Get Competitor Traffic |
+| [`getSettings`](#op-getsettings) | `GET /api/v1/radar/settings` | read | `radar:read` | Get Settings |
+| [`keywordGap`](#op-keywordgap) | `GET /api/v1/radar/keyword-gap` | read | `radar:run` | Keyword Gap |
+| [`listCompetitors`](#op-listcompetitors) | `GET /api/v1/radar/competitors` | read | `radar:read` | List Competitors |
+| [`listGaps`](#op-listgaps) | `GET /api/v1/radar/gaps` | read | `radar:read` | List Gaps |
+| [`listInitiatives`](#op-listinitiatives) | `GET /api/v1/radar/initiatives` | read | `radar:read` | List Initiatives |
+| [`listOpportunities`](#op-listopportunities) | `GET /api/v1/radar/opportunities` | read | `radar:read` | List Opportunities |
+| [`measureInitiatives`](#op-measureinitiatives) | `POST /api/v1/radar/initiatives/measure` | billable | `radar:run` | Measure Initiatives |
+| [`monitoringAdDetail`](#op-monitoringaddetail) | `GET /api/v1/radar/monitoring/ads/{ad_id}` | read | `radar:read` | Monitoring Ad Detail |
+| [`monitoringAds`](#op-monitoringads) | `GET /api/v1/radar/monitoring/ads` | read | `radar:run` | Monitoring Ads |
+| [`monitoringContent`](#op-monitoringcontent) | `GET /api/v1/radar/monitoring/content` | read | `radar:read` | Monitoring Content |
+| [`monitoringLinkedin`](#op-monitoringlinkedin) | `GET /api/v1/radar/monitoring/linkedin` | read | `radar:read` | Monitoring Linkedin |
+| [`optimizationRuns`](#op-optimizationruns) | `GET /api/v1/radar/optimization-runs` | read | `radar:read` | Optimization Runs |
+| [`overview`](#op-overview) | `GET /api/v1/radar/overview` | read | `radar:read` | Overview |
+| [`ownTrafficEstimate`](#op-owntrafficestimate) | `GET /api/v1/radar/own-traffic-estimate` | read | `radar:run` | Own Traffic Estimate |
+| [`pageHistory`](#op-pagehistory) | `GET /api/v1/radar/monitoring/page-history` | read | `radar:read` | Page History |
+| [`putSettings`](#op-putsettings) | `PUT /api/v1/radar/settings` | billable | `radar:write` | Put Settings |
+| [`scanAllCompetitors`](#op-scanallcompetitors) | `POST /api/v1/radar/scan-all` | billable | `radar:run` | Scan All Competitors |
+| [`scanCompetitor`](#op-scancompetitor) | `POST /api/v1/radar/competitors/{competitor_id}/scan` | billable | `radar:run` | Scan Competitor |
+| [`traffic`](#op-traffic) | `GET /api/v1/radar/traffic` | read | `radar:read` | Traffic |
+| [`updateCompetitor`](#op-updatecompetitor) | `PATCH /api/v1/radar/competitors/{competitor_id}` | billable | `radar:write` | Update Competitor |
+| [`updateGap`](#op-updategap) | `PATCH /api/v1/radar/gaps/{gap_id}` | billable | `radar:write` | Update Gap |
+
+---
+
+<a id="op-aeooverview"></a>
+
+### `g8.api.radar.aeoOverview(input?)`
+
+**Aeo Overview**
+
+- HTTP: `GET /api/v1/radar/aeo`
+- operationId: `aeo_overview_radar_aeo_get` (also callable as `g8.api.call("aeo_overview_radar_aeo_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Answer-engine share-of-voice: mention/citation rate, SoV, leaderboard.
+
+``engine`` is passed through as a RESOLVED value. Called directly (not via
+FastAPI), an omitted param would keep its ``Query(default=None)`` sentinel,
+which the cb handler reads as a truthy unsupported engine and rejects with a
+400 on every call - so the value must be forwarded explicitly.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.engine` | `string \| null` | no | Filter to one answer engine (e.g. claude, perplexity). |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.aeoOverview();
+```
+
+---
+
+<a id="op-aeoprobes"></a>
+
+### `g8.api.radar.aeoProbes(input?)`
+
+**Aeo Probes**
+
+- HTTP: `GET /api/v1/radar/aeo/probes`
+- operationId: `aeo_probes_radar_aeo_probes_get` (also callable as `g8.api.call("aeo_probes_radar_aeo_probes_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+List the org's tracked AEO buyer-intent probes.
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.aeoProbes();
+```
+
+---
+
+<a id="op-aeorun"></a>
+
+### `g8.api.radar.aeoRun(input?)`
+
+**Aeo Run**
+
+- HTTP: `POST /api/v1/radar/aeo/run`
+- operationId: `aeo_run_radar_aeo_run_post` (also callable as `g8.api.call("aeo_run_radar_aeo_run_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `radar:run`
+
+BILLABLE: trigger an AEO run (one paid LLM call per probe, Celery).
+
+The cb function declares a settings:write dependency; we pass _=None so the
+gate is satisfied at the public surface (RBAC specs out of scope).
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.radar.aeoRun();
+```
+
+---
+
+<a id="op-analyzegaps"></a>
+
+### `g8.api.radar.analyzeGaps(input)`
+
+**Analyze Gaps**
+
+- HTTP: `POST /api/v1/radar/gaps/analyze`
+- operationId: `analyze_gaps_radar_gaps_analyze_post` (also callable as `g8.api.call("analyze_gaps_radar_gaps_analyze_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `radar:run`
+
+BILLABLE: enqueue gap analysis across the tracked set (LLM, Celery).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `AnalyzeGapsRequest` | yes | Request body; fields below. |
+
+Body fields (`AnalyzeGapsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.lenses` | `Array<string> \| null` | no |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.radar.analyzeGaps({ body: {} });
+```
+
+---
+
+<a id="op-approveallopportunities"></a>
+
+### `g8.api.radar.approveAllOpportunities(input)`
+
+**Approve All Opportunities**
+
+- HTTP: `POST /api/v1/radar/opportunities/approve-all`
+- operationId: `approve_all_opportunities_radar_opportunities_approve_all_post` (also callable as `g8.api.call("approve_all_opportunities_radar_opportunities_approve_all_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `radar:write`
+
+Bulk-approve opportunities in one lane - currently FAIL-CLOSED (HTTP 409).
+
+campaign_builder deliberately rejects bulk approval until an item-by-item
+review contract exists: ``approve_all_opportunities`` raises 409 'Bulk
+approval requires review' on every call (campaign_builder/routers/radar.py).
+This bridge forwards to that handler so the 409 is surfaced honestly instead
+of fabricating a 200 - it never mutates or bills. Approve opportunities one
+at a time via ``POST /radar/opportunities/{gap_id}/approve``.
+
+Product gap (out of this bridge's scope): the developer-api reference
+(docs/developer-api-reference.md ~L3799-3800) and the MCP tool
+g8_radar_approve_all_opportunities still advertise a working 'top-50 drain'
+and must be re-documented to the 409 contract, or the cb handler must gain a
+real bulk-review flow.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ApproveAllRequest` | yes | Request body; fields below. |
+
+Body fields (`ApproveAllRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.lane` | `string` | no | default `"now"` |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.radar.approveAllOpportunities({ body: {} });
+```
+
+---
+
+<a id="op-approveopportunity"></a>
+
+### `g8.api.radar.approveOpportunity(input)`
+
+**Approve Opportunity**
+
+- HTTP: `POST /api/v1/radar/opportunities/{gap_id}/approve`
+- operationId: `approve_opportunity_radar_opportunities__gap_id__approve_post` (also callable as `g8.api.call("approve_opportunity_radar_opportunities__gap_id__approve_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `radar:write`
+
+Approve one scored opportunity - converts it into an initiative + stubs.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.gap_id` | `string` | yes |  |
+| `body` | `ApproveOpportunityRequest` | yes | Request body; fields below. |
+
+Body fields (`ApproveOpportunityRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.content_types` | `Array<string> \| null` | no |  |
+| `body.create_crm_task` | `boolean` | no | default `false` |
+| `body.due_date` | `string (date) \| null` | no |  |
+| `body.kinds` | `Array<string> \| null` | no |  |
+| `body.owner_id` | `string \| null` | no |  |
+| `body.seed_context` | `SeedContext \| null` | no |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.radar.approveOpportunity({ path: { gap_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-bulkaddcompetitors"></a>
+
+### `g8.api.radar.bulkAddCompetitors(input)`
+
+**Bulk Add Competitors**
+
+- HTTP: `POST /api/v1/radar/competitors/bulk`
+- operationId: `bulk_add_competitors_radar_competitors_bulk_post` (also callable as `g8.api.call("bulk_add_competitors_radar_competitors_bulk_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `radar:write`
+
+Add many competitors at once (normalize + dedup + 20-competitor cap).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `BulkCompetitorsRequest` | yes | Request body; fields below. |
+
+Body fields (`BulkCompetitorsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.competitors` | `Array<BulkCompetitorItem>` | no | max items 20 |
+| `body.scan_on_add` | `boolean` | no | default `false` |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.radar.bulkAddCompetitors({ body: {} });
+```
+
+---
+
+<a id="op-comparesnapshot"></a>
+
+### `g8.api.radar.compareSnapshot(input)`
+
+**Compare Snapshot**
+
+- HTTP: `GET /api/v1/radar/snapshots/{snapshot_id}/compare`
+- operationId: `compare_snapshot_radar_snapshots__snapshot_id__compare_get` (also callable as `g8.api.call("compare_snapshot_radar_snapshots__snapshot_id__compare_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Before/after diff for one page snapshot (vs prior capture or `against`).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.snapshot_id` | `string` | yes |  |
+| `query.against` | `string \| null` | no |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.compareSnapshot({ path: { snapshot_id: "id" } });
+```
+
+---
+
+<a id="op-competitorbattlecard"></a>
+
+### `g8.api.radar.competitorBattleCard(input)`
+
+**Competitor Battle Card**
+
+- HTTP: `GET /api/v1/radar/competitors/{competitor_id}/battle-card`
+- operationId: `competitor_battle_card_radar_competitors__competitor_id__battle_card_get` (also callable as `g8.api.call("competitor_battle_card_radar_competitors__competitor_id__battle_card_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Sales-enablement battle card composed from existing Radar intel (no LLM).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.competitor_id` | `string` | yes |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.competitorBattleCard({ path: { competitor_id: "id" } });
+```
+
+---
+
+<a id="op-competitorsuggestions"></a>
+
+### `g8.api.radar.competitorSuggestions(input?)`
+
+**Competitor Suggestions**
+
+- HTTP: `GET /api/v1/radar/competitors/suggestions`
+- operationId: `competitor_suggestions_radar_competitors_suggestions_get` (also callable as `g8.api.call("competitor_suggestions_radar_competitors_suggestions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Detected-but-untracked competitors from intelligence + global docs.
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.competitorSuggestions();
+```
+
+---
+
+<a id="op-createcompetitor"></a>
+
+### `g8.api.radar.createCompetitor(input)`
+
+**Create Competitor**
+
+- HTTP: `POST /api/v1/radar/competitors`
+- operationId: `create_competitor_radar_competitors_post` (also callable as `g8.api.call("create_competitor_radar_competitors_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `radar:write`
+
+Add one competitor to track. 409 if already tracked, 422 at the cap.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CreateCompetitorRequest` | yes | Request body; fields below. |
+
+Body fields (`CreateCompetitorRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.domain` | `string` | yes | min length 1, max length 255 |
+| `body.name` | `string \| null` | no | max length 255 |
+| `body.scan_config` | `ScanConfigDTO \| null` | no |  |
+| `body.scan_on_add` | `boolean` | no | default `false` |
+| `body.tier` | `string \| null` | no | default `"tier2"` |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.radar.createCompetitor({ body: { domain: "acme.com" } });
+```
+
+---
+
+<a id="op-deletecompetitor"></a>
+
+### `g8.api.radar.deleteCompetitor(input)`
+
+**Delete Competitor**
+
+- HTTP: `DELETE /api/v1/radar/competitors/{competitor_id}`
+- operationId: `delete_competitor_radar_competitors__competitor_id__delete` (also callable as `g8.api.call("delete_competitor_radar_competitors__competitor_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `radar:delete`
+
+Deactivate a tracked competitor while retaining its evidence history.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.competitor_id` | `string` | yes |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.radar.deleteCompetitor({ path: { competitor_id: "id" } });
+```
+
+---
+
+<a id="op-discovercompetitorpages"></a>
+
+### `g8.api.radar.discoverCompetitorPages(input)`
+
+**Discover Competitor Pages**
+
+- HTTP: `GET /api/v1/radar/competitors/{competitor_id}/discover-pages`
+- operationId: `discover_competitor_pages_radar_competitors__competitor_id__discover_pages_get` (also callable as `g8.api.call("discover_competitor_pages_radar_competitors__competitor_id__discover_pages_get", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `radar:run`
+
+Discover a competitor's pages (Firecrawl /map) for the tracked-pages picker.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.competitor_id` | `string` | yes |  |
+| `query.refresh` | `boolean` | no | Bypass the cached page inventory and re-map the site (paid). default `false` |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.radar.discoverCompetitorPages({ path: { competitor_id: "id" } });
+```
+
+---
+
+<a id="op-dispatchalerts"></a>
+
+### `g8.api.radar.dispatchAlerts(input?)`
+
+**Dispatch Alerts**
+
+- HTTP: `POST /api/v1/radar/alerts/dispatch`
+- operationId: `dispatch_alerts_radar_alerts_dispatch_post` (also callable as `g8.api.call("dispatch_alerts_radar_alerts_dispatch_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `radar:run`
+
+Detect + deliver new competitor-move alerts now. Returns {delivered}.
+
+The cb function declares a settings:write dependency; we pass _=None so the
+gate is satisfied at the public surface (RBAC specs out of scope).
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.radar.dispatchAlerts();
+```
+
+---
+
+<a id="op-featurematrix"></a>
+
+### `g8.api.radar.featureMatrix(input?)`
+
+**Feature Matrix**
+
+- HTTP: `GET /api/v1/radar/feature-matrix`
+- operationId: `feature_matrix_radar_feature_matrix_get` (also callable as `g8.api.call("feature_matrix_radar_feature_matrix_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Capability/feature comparison matrix across the tracked competitor set.
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.featureMatrix();
+```
+
+---
+
+<a id="op-getcompetitor"></a>
+
+### `g8.api.radar.getCompetitor(input)`
+
+**Get Competitor**
+
+- HTTP: `GET /api/v1/radar/competitors/{competitor_id}`
+- operationId: `get_competitor_radar_competitors__competitor_id__get` (also callable as `g8.api.call("get_competitor_radar_competitors__competitor_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Single-competitor aggregation: profile + pages-tracked + recent changes + gaps.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.competitor_id` | `string` | yes |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.getCompetitor({ path: { competitor_id: "id" } });
+```
+
+---
+
+<a id="op-getcompetitorads"></a>
+
+### `g8.api.radar.getCompetitorAds(input)`
+
+**Get Competitor Ads**
+
+- HTTP: `GET /api/v1/radar/competitors/{competitor_id}/ads`
+- operationId: `get_competitor_ads_radar_competitors__competitor_id__ads_get` (also callable as `g8.api.call("get_competitor_ads_radar_competitors__competitor_id__ads_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Captured ad creatives for one competitor (durable snapshot corpus).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.competitor_id` | `string` | yes |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.getCompetitorAds({ path: { competitor_id: "id" } });
+```
+
+---
+
+<a id="op-getcompetitorengagers"></a>
+
+### `g8.api.radar.getCompetitorEngagers(input)`
+
+**Get Competitor Engagers**
+
+- HTTP: `GET /api/v1/radar/competitors/{competitor_id}/engagers`
+- operationId: `get_competitor_engagers_radar_competitors__competitor_id__engagers_get` (also callable as `g8.api.call("get_competitor_engagers_radar_competitors__competitor_id__engagers_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Steal-Their-Audience: known-to-us people who engage this rival's content.
+
+The cb function declares a deals-read permission dependency; here we pass a
+synthesized org-admin principal (``_=True``) so the gate is satisfied at the
+public surface (RBAC specs out of scope by decision).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.competitor_id` | `string` | yes |  |
+| `query.limit` | `integer` | no | default `100` |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.getCompetitorEngagers({ path: { competitor_id: "id" } });
+```
+
+---
+
+<a id="op-getcompetitorpages"></a>
+
+### `g8.api.radar.getCompetitorPages(input)`
+
+**Get Competitor Pages**
+
+- HTTP: `GET /api/v1/radar/competitors/{competitor_id}/pages`
+- operationId: `get_competitor_pages_radar_competitors__competitor_id__pages_get` (also callable as `g8.api.call("get_competitor_pages_radar_competitors__competitor_id__pages_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Distinct tracked pages for one competitor (latest snapshot per URL).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.competitor_id` | `string` | yes |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.getCompetitorPages({ path: { competitor_id: "id" } });
+```
+
+---
+
+<a id="op-getcompetitorposts"></a>
+
+### `g8.api.radar.getCompetitorPosts(input)`
+
+**Get Competitor Posts**
+
+- HTTP: `GET /api/v1/radar/competitors/{competitor_id}/posts`
+- operationId: `get_competitor_posts_radar_competitors__competitor_id__posts_get` (also callable as `g8.api.call("get_competitor_posts_radar_competitors__competitor_id__posts_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+LinkedIn posts for one competitor (listener store, then corpus fallback).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.competitor_id` | `string` | yes |  |
+| `query.limit` | `integer` | no | default `50` |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.getCompetitorPosts({ path: { competitor_id: "id" } });
+```
+
+---
+
+<a id="op-getcompetitortraffic"></a>
+
+### `g8.api.radar.getCompetitorTraffic(input)`
+
+**Get Competitor Traffic**
+
+- HTTP: `GET /api/v1/radar/competitors/{competitor_id}/traffic`
+- operationId: `get_competitor_traffic_radar_competitors__competitor_id__traffic_get` (also callable as `g8.api.call("get_competitor_traffic_radar_competitors__competitor_id__traffic_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Traffic detail for one competitor: current estimate + trend + ETV history.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.competitor_id` | `string` | yes |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.getCompetitorTraffic({ path: { competitor_id: "id" } });
+```
+
+---
+
+<a id="op-getsettings"></a>
+
+### `g8.api.radar.getSettings(input?)`
+
+**Get Settings**
+
+- HTTP: `GET /api/v1/radar/settings`
+- operationId: `get_settings_radar_settings_get` (also callable as `g8.api.call("get_settings_radar_settings_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Read the org's Radar settings (cadence, alert toggles, channels, ad_source).
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.getSettings();
+```
+
+---
+
+<a id="op-keywordgap"></a>
+
+### `g8.api.radar.keywordGap(input?)`
+
+**Keyword Gap**
+
+- HTTP: `GET /api/v1/radar/keyword-gap`
+- operationId: `keyword_gap_radar_keyword_gap_get` (also callable as `g8.api.call("keyword_gap_radar_keyword_gap_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:run`
+
+Keywords each rival ranks for that the org does NOT ("what you're missing").
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.keywordGap();
+```
+
+---
+
+<a id="op-listcompetitors"></a>
+
+### `g8.api.radar.listCompetitors(input?)`
+
+**List Competitors**
+
+- HTTP: `GET /api/v1/radar/competitors`
+- operationId: `list_competitors_radar_competitors_get` (also callable as `g8.api.call("list_competitors_radar_competitors_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Every tracked competitor profile (active + inactive), tier then domain.
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.listCompetitors();
+```
+
+---
+
+<a id="op-listgaps"></a>
+
+### `g8.api.radar.listGaps(input?)`
+
+**List Gaps**
+
+- HTTP: `GET /api/v1/radar/gaps`
+- operationId: `list_gaps_radar_gaps_get` (also callable as `g8.api.call("list_gaps_radar_gaps_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+List competitive gaps, optionally filtered by lens / status / competitor.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.lens` | `string \| null` | no |  |
+| `query.status` | `string \| null` | no |  |
+| `query.competitor_id` | `string \| null` | no |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.listGaps();
+```
+
+---
+
+<a id="op-listinitiatives"></a>
+
+### `g8.api.radar.listInitiatives(input?)`
+
+**List Initiatives**
+
+- HTTP: `GET /api/v1/radar/initiatives`
+- operationId: `list_initiatives_radar_initiatives_get` (also callable as `g8.api.call("list_initiatives_radar_initiatives_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+List radar initiatives (converted opportunities under execution).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.lane` | `string \| null` | no |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.listInitiatives();
+```
+
+---
+
+<a id="op-listopportunities"></a>
+
+### `g8.api.radar.listOpportunities(input?)`
+
+**List Opportunities**
+
+- HTTP: `GET /api/v1/radar/opportunities`
+- operationId: `list_opportunities_radar_opportunities_get` (also callable as `g8.api.call("list_opportunities_radar_opportunities_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+List opportunities - the scored OPEN gaps, optionally filtered by lane.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.lane` | `string \| null` | no |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.listOpportunities();
+```
+
+---
+
+<a id="op-measureinitiatives"></a>
+
+### `g8.api.radar.measureInitiatives(input?)`
+
+**Measure Initiatives**
+
+- HTTP: `POST /api/v1/radar/initiatives/measure`
+- operationId: `measure_initiatives_radar_initiatives_measure_post` (also callable as `g8.api.call("measure_initiatives_radar_initiatives_measure_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `radar:run`
+
+Run the performance loopback now (free, DB-only). Returns {measured}.
+
+The cb function declares a settings:write dependency; we pass _=None so the
+gate is satisfied at the public surface (RBAC specs out of scope).
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.radar.measureInitiatives();
+```
+
+---
+
+<a id="op-monitoringaddetail"></a>
+
+### `g8.api.radar.monitoringAdDetail(input)`
+
+**Monitoring Ad Detail**
+
+- HTTP: `GET /api/v1/radar/monitoring/ads/{ad_id}`
+- operationId: `monitoring_ad_detail_radar_monitoring_ads__ad_id__get` (also callable as `g8.api.call("monitoring_ad_detail_radar_monitoring_ads__ad_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+One ad's full detail (copy / headline / image / dates) + rival context.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.ad_id` | `string` | yes |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.monitoringAdDetail({ path: { ad_id: "id" } });
+```
+
+---
+
+<a id="op-monitoringads"></a>
+
+### `g8.api.radar.monitoringAds(input?)`
+
+**Monitoring Ads**
+
+- HTTP: `GET /api/v1/radar/monitoring/ads`
+- operationId: `monitoring_ads_radar_monitoring_ads_get` (also callable as `g8.api.call("monitoring_ads_radar_monitoring_ads_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:run`
+
+Ads & keywords: durable ad_creative corpus + persisted organic/paid keywords.
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.monitoringAds();
+```
+
+---
+
+<a id="op-monitoringcontent"></a>
+
+### `g8.api.radar.monitoringContent(input?)`
+
+**Monitoring Content**
+
+- HTTP: `GET /api/v1/radar/monitoring/content`
+- operationId: `monitoring_content_radar_monitoring_content_get` (also callable as `g8.api.call("monitoring_content_radar_monitoring_content_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Competitor content-change feed with the same filters as the cb route.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.competitor_id` | `string \| null` | no |  |
+| `query.kind` | `string \| null` | no |  |
+| `query.change_category` | `string \| null` | no |  |
+| `query.change_type` | `string \| null` | no |  |
+| `query.min_significance` | `integer \| null` | no |  |
+| `query.date_from` | `string \| null` | no |  |
+| `query.date_to` | `string \| null` | no |  |
+| `query.search` | `string \| null` | no |  |
+| `query.limit` | `integer` | no | default `50` |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.monitoringContent();
+```
+
+---
+
+<a id="op-monitoringlinkedin"></a>
+
+### `g8.api.radar.monitoringLinkedin(input?)`
+
+**Monitoring Linkedin**
+
+- HTTP: `GET /api/v1/radar/monitoring/linkedin`
+- operationId: `monitoring_linkedin_radar_monitoring_linkedin_get` (also callable as `g8.api.call("monitoring_linkedin_radar_monitoring_linkedin_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Competitor LinkedIn posts (listener store first, then corpus fallback).
+
+Every filter is forwarded as a RESOLVED value. Called directly (not via
+FastAPI), omitted ``date_from``/``date_to`` params would keep their
+``Query`` sentinels, and the cb handler's ``date_from > date_to`` guard then
+raises ``TypeError`` (Query vs Query) -> a 500 on every call. Passing the
+coerced ``date``/``None`` values instead lets the guard emit a clean 422 on
+an inverted range and exposes the page/domain/date filters the cb route
+supports.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.page` | `integer` | no | default `1` |
+| `query.limit` | `integer` | no | default `50` |
+| `query.competitor_domain` | `string \| null` | no |  |
+| `query.date_from` | `string (date) \| null` | no |  |
+| `query.date_to` | `string (date) \| null` | no |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.monitoringLinkedin();
+```
+
+---
+
+<a id="op-optimizationruns"></a>
+
+### `g8.api.radar.optimizationRuns(input?)`
+
+**Optimization Runs**
+
+- HTTP: `GET /api/v1/radar/optimization-runs`
+- operationId: `optimization_runs_radar_optimization_runs_get` (also callable as `g8.api.call("optimization_runs_radar_optimization_runs_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Radar-spawned content-refresh grids with lean score aggregates.
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.optimizationRuns();
+```
+
+---
+
+<a id="op-overview"></a>
+
+### `g8.api.radar.overview(input?)`
+
+**Overview**
+
+- HTTP: `GET /api/v1/radar/overview`
+- operationId: `overview_radar_overview_get` (also callable as `g8.api.call("overview_radar_overview_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Radar dashboard summary: tracked counts, 7-day moves, the threat board,
+recent moves, pipeline funnel, and derived alerts.
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.overview();
+```
+
+---
+
+<a id="op-owntrafficestimate"></a>
+
+### `g8.api.radar.ownTrafficEstimate(input?)`
+
+**Own Traffic Estimate**
+
+- HTTP: `GET /api/v1/radar/own-traffic-estimate`
+- operationId: `own_traffic_estimate_radar_own_traffic_estimate_get` (also callable as `g8.api.call("own_traffic_estimate_radar_own_traffic_estimate_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:run`
+
+Estimated own-domain traffic (DataForSEO) - Traffic & market fallback.
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.ownTrafficEstimate();
+```
+
+---
+
+<a id="op-pagehistory"></a>
+
+### `g8.api.radar.pageHistory(input)`
+
+**Page History**
+
+- HTTP: `GET /api/v1/radar/monitoring/page-history`
+- operationId: `page_history_radar_monitoring_page_history_get` (also callable as `g8.api.call("page_history_radar_monitoring_page_history_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Full capture history for one page (competitor + url), newest-first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.url` | `string` | yes |  |
+| `query.competitor_id` | `string` | yes |  |
+| `query.limit` | `integer` | no | default `20` |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.pageHistory({ query: { url: "https://example.com", competitor_id: "id" } });
+```
+
+---
+
+<a id="op-putsettings"></a>
+
+### `g8.api.radar.putSettings(input)`
+
+**Put Settings**
+
+- HTTP: `PUT /api/v1/radar/settings`
+- operationId: `put_settings_radar_settings_put` (also callable as `g8.api.call("put_settings_radar_settings_put", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `radar:write`
+
+Replace the org's Radar settings (full object).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `RadarSettings` | yes | Request body; fields below. |
+
+Body fields (`RadarSettings`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.ad_source` | `"stored" \| "linkedin" \| "meta" \| "google" \| "all"` | no | default `"stored"` |
+| `body.alerts` | `RadarAlerts` | no |  |
+| `body.channels` | `RadarChannels` | no |  |
+| `body.monthly_credit_cap` | `integer \| null` | no | min 0 |
+| `body.tier1_cadence_days` | `integer` | no | default `7`, min 1, max 365 |
+| `body.tier2_cadence_days` | `integer` | no | default `30`, min 1, max 365 |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.radar.putSettings({ body: {} });
+```
+
+---
+
+<a id="op-scanallcompetitors"></a>
+
+### `g8.api.radar.scanAllCompetitors(input?)`
+
+**Scan All Competitors**
+
+- HTTP: `POST /api/v1/radar/scan-all`
+- operationId: `scan_all_competitors_radar_scan_all_post` (also callable as `g8.api.call("scan_all_competitors_radar_scan_all_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `radar:run`
+
+BILLABLE: enqueue a scan for every active competitor (Celery).
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.radar.scanAllCompetitors();
+```
+
+---
+
+<a id="op-scancompetitor"></a>
+
+### `g8.api.radar.scanCompetitor(input)`
+
+**Scan Competitor**
+
+- HTTP: `POST /api/v1/radar/competitors/{competitor_id}/scan`
+- operationId: `scan_competitor_radar_competitors__competitor_id__scan_post` (also callable as `g8.api.call("scan_competitor_radar_competitors__competitor_id__scan_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `radar:run`
+
+BILLABLE: enqueue a fresh scan of one competitor (Celery). Returns {task_id}.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.competitor_id` | `string` | yes |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.radar.scanCompetitor({ path: { competitor_id: "id" } });
+```
+
+---
+
+<a id="op-traffic"></a>
+
+### `g8.api.radar.traffic(input?)`
+
+**Traffic**
+
+- HTTP: `GET /api/v1/radar/traffic`
+- operationId: `traffic_radar_traffic_get` (also callable as `g8.api.call("traffic_radar_traffic_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `radar:read`
+
+Traffic & market view: per-competitor visit estimates + trend (self marked).
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.radar.traffic();
+```
+
+---
+
+<a id="op-updatecompetitor"></a>
+
+### `g8.api.radar.updateCompetitor(input)`
+
+**Update Competitor**
+
+- HTTP: `PATCH /api/v1/radar/competitors/{competitor_id}`
+- operationId: `update_competitor_radar_competitors__competitor_id__patch` (also callable as `g8.api.call("update_competitor_radar_competitors__competitor_id__patch", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `radar:write`
+
+Update a competitor profile (tier, active flag, name, or scan_config).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.competitor_id` | `string` | yes |  |
+| `body` | `PatchCompetitorRequest` | yes | Request body; fields below. |
+
+Body fields (`PatchCompetitorRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.is_active` | `boolean \| null` | no |  |
+| `body.name` | `string \| null` | no | max length 255 |
+| `body.scan_config` | `ScanConfigDTO \| null` | no |  |
+| `body.tier` | `string \| null` | no |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.radar.updateCompetitor({ path: { competitor_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-updategap"></a>
+
+### `g8.api.radar.updateGap(input)`
+
+**Update Gap**
+
+- HTTP: `PATCH /api/v1/radar/gaps/{gap_id}`
+- operationId: `update_gap_radar_gaps__gap_id__patch` (also callable as `g8.api.call("update_gap_radar_gaps__gap_id__patch", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `radar:write`
+
+Update a gap's status (open / dismissed / converted).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.gap_id` | `string` | yes |  |
+| `body` | `PatchGapRequest` | yes | Request body; fields below. |
+
+Body fields (`PatchGapRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.status` | `string` | yes |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.radar.updateGap({ path: { gap_id: "id" }, body: { status: "example" } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-bulkcompetitoritem"></a>
+
+### `BulkCompetitorItem`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `domain` | `string` | yes | min length 1, max length 255 |
+| `name` | `string \| null` | no | max length 255 |
+| `scan_config` | `ScanConfigDTO \| null` | no |  |
+| `tier` | `string \| null` | no |  |
+
+<a id="type-radaralerts"></a>
+
+### `RadarAlerts`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `case_files` | `boolean` | no | default `true` |
+| `content_velocity` | `boolean` | no | default `true` |
+| `hiring_spike` | `boolean` | no | default `true` |
+| `keyword_overtake` | `boolean` | no | default `true` |
+| `new_ads` | `boolean` | no | default `true` |
+| `pricing_change` | `boolean` | no | default `true` |
+| `warm_account` | `boolean` | no | default `true` |
+
+<a id="type-radarchannels"></a>
+
+### `RadarChannels`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `bridge` | `boolean` | no | default `false` |
+| `in_app` | `boolean` | no | default `true` |
+
+<a id="type-scanconfigdto"></a>
+
+### `ScanConfigDTO`
+
+Per-competitor page-selection config (persisted on profile.meta.scan_config). mode=auto: Firecrawl /map → rank by traffic + pricing/feature paths → scrape top N (= tier page budget). mode=manual: scrape include_paths (literal or /wildcard/* patterns), capped to the budget.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `include_paths` | `Array<string>` | no | max items 50 |
+| `mode` | `"auto" \| "manual"` | no | default `"auto"` |
+
+<a id="type-seedcontext"></a>
+
+### `SeedContext`
+
+Optional richer seed for an approved stub — e.g. the target keyword (+ volume/cpc) to seed an SEO page with. All optional; absent → current behavior unchanged.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `cpc` | `number \| null` | no |  |
+| `primary_keyword` | `string \| null` | no | max length 255 |
+| `volume` | `integer \| null` | no |  |