@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/intent.md

@@ -0,0 +1,858 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.intent`: Intent
+
+16 operations (2 read, 1 destructive, 13 billable).
+
+13 of these also have a hand-written method (`g8.intent`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
+
+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: [intent.d.ts](intent.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`intentStats`](#op-intentstats) ★ | `GET /api/v1/intent/stats` | read | `intent:read` | Intent Stats |
+| [`keywordCompanies`](#op-keywordcompanies) ★ | `POST /api/v1/intent/keywords/{keyword_id}/companies` | billable | `intent:run` | Keyword Companies |
+| [`keywordContacts`](#op-keywordcontacts) ★ | `POST /api/v1/intent/keywords/{keyword_id}/contacts` | billable | `intent:run` | Keyword Contacts |
+| [`keywordUpdateFilters`](#op-keywordupdatefilters) | `POST /api/v1/intent/keywords/{keyword_id}/filters` | billable | `intent:run` | Keyword Update Filters |
+| [`keywordUrls`](#op-keywordurls) ★ | `POST /api/v1/intent/keywords/{keyword_id}/urls` | billable | `intent:run` | Keyword Urls |
+| [`keywordsAdd`](#op-keywordsadd) | `POST /api/v1/intent/keywords/add` | billable | `intent:run` | Keywords Add |
+| [`keywordsCreateFromDomain`](#op-keywordscreatefromdomain) ★ | `POST /api/v1/intent/keywords/create-from-domain` | billable | `intent:run` | Keywords Create From Domain |
+| [`keywordsCreateFromSearch`](#op-keywordscreatefromsearch) | `POST /api/v1/intent/keywords/create-from-search` | billable | `intent:run` | Keywords Create From Search |
+| [`keywordsDelete`](#op-keywordsdelete) ★ | `DELETE /api/v1/intent/keywords/{keyword_id}` | destructive | `intent:delete` | Keywords Delete |
+| [`keywordsList`](#op-keywordslist) ★ | `POST /api/v1/intent/keywords/list` | billable | `intent:run` | Keywords List |
+| [`pagesByDomain`](#op-pagesbydomain) ★ | `POST /api/v1/intent/pages-by-domain` | billable | `intent:run` | Pages By Domain |
+| [`pagesContacts`](#op-pagescontacts) ★ | `POST /api/v1/intent/pages/contacts` | billable | `intent:run` | Pages Contacts |
+| [`pagesSearch`](#op-pagessearch) ★ | `POST /api/v1/intent/pages/search` | billable | `intent:run` | Pages Search |
+| [`pagesVisitorCounts`](#op-pagesvisitorcounts) ★ | `POST /api/v1/intent/pages/visitor-counts` | billable | `intent:run` | Pages Visitor Counts |
+| [`pagesVisitors`](#op-pagesvisitors) ★ | `POST /api/v1/intent/pages/visitors` | billable | `intent:run` | Pages Visitors |
+| [`urlCompanies`](#op-urlcompanies) ★ | `POST /api/v1/intent/url-companies` | read | `intent:read` | Url Companies |
+
+---
+
+<a id="op-intentstats"></a>
+
+### `g8.api.intent.intentStats(input?)`
+
+**Intent Stats**
+
+- HTTP: `GET /api/v1/intent/stats`
+- operationId: `intent_stats_intent_stats_get` (also callable as `g8.api.call("intent_stats_intent_stats_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+- ★ Hand-written: [`g8.intent.stats()`](../sdk-clients.md#g8-intent-stats)
+
+Index-coverage stats: document count + size.
+
+Useful for health checks before committing to a compete-tracking program.
+
+**Input**: none.
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.intent.intentStats();
+```
+
+---
+
+<a id="op-keywordcompanies"></a>
+
+### `g8.api.intent.keywordCompanies(input)`
+
+**Keyword Companies**
+
+- HTTP: `POST /api/v1/intent/keywords/{keyword_id}/companies`
+- operationId: `keyword_companies_intent_keywords__keyword_id__companies_post` (also callable as `g8.api.call("keyword_companies_intent_keywords__keyword_id__companies_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+- ★ Hand-written: [`g8.intent.keywordCompanies()`](../sdk-clients.md#g8-intent-keywordcompanies)
+
+Companies resolved against a keyword's URL set (intent_resolved).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.keyword_id` | `string (uuid)` | yes |  |
+| `body` | `KeywordDetailRequest` | yes | Request body; fields below. |
+
+Body fields (`KeywordDetailRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.conditions` | `Array<Record<string, unknown>>` | no | Optional `[{field, operator, value}]` filter conditions. |
+| `body.limit` | `integer` | no | default `100`, min 1, max 500 |
+| `body.page` | `integer` | no | default `1`, min 1 |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.intent.keywordCompanies({
+  path: { keyword_id: "00000000-0000-0000-0000-000000000000" },
+  body: {},
+});
+```
+
+---
+
+<a id="op-keywordcontacts"></a>
+
+### `g8.api.intent.keywordContacts(input)`
+
+**Keyword Contacts**
+
+- HTTP: `POST /api/v1/intent/keywords/{keyword_id}/contacts`
+- operationId: `keyword_contacts_intent_keywords__keyword_id__contacts_post` (also callable as `g8.api.call("keyword_contacts_intent_keywords__keyword_id__contacts_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+- ★ Hand-written: [`g8.intent.keywordContacts()`](../sdk-clients.md#g8-intent-keywordcontacts)
+
+People resolved against a keyword's URL set (intent_resolved).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.keyword_id` | `string (uuid)` | yes |  |
+| `body` | `KeywordDetailRequest` | yes | Request body; fields below. |
+
+Body fields (`KeywordDetailRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.conditions` | `Array<Record<string, unknown>>` | no | Optional `[{field, operator, value}]` filter conditions. |
+| `body.limit` | `integer` | no | default `100`, min 1, max 500 |
+| `body.page` | `integer` | no | default `1`, min 1 |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.intent.keywordContacts({
+  path: { keyword_id: "00000000-0000-0000-0000-000000000000" },
+  body: {},
+});
+```
+
+---
+
+<a id="op-keywordupdatefilters"></a>
+
+### `g8.api.intent.keywordUpdateFilters(input)`
+
+**Keyword Update Filters**
+
+- HTTP: `POST /api/v1/intent/keywords/{keyword_id}/filters`
+- operationId: `keyword_update_filters_intent_keywords__keyword_id__filters_post` (also callable as `g8.api.call("keyword_update_filters_intent_keywords__keyword_id__filters_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Replace a keyword's `search_filters` JSON.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.keyword_id` | `string (uuid)` | yes |  |
+| `body` | `KeywordFiltersUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`KeywordFiltersUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.search_filters` | `Record<string, unknown>` | yes | Full-replacement `search_filters` JSON. Typed fields in `intent.domain.models.keyword.KeywordSearchFilters`: audience, exclude_page_types, min_commercial_intent_level, max_urls_per_domain, llm_triage, exclude_domains. Extra keys allowed. |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.intent.keywordUpdateFilters({
+  path: { keyword_id: "00000000-0000-0000-0000-000000000000" },
+  body: { search_filters: {} },
+});
+```
+
+---
+
+<a id="op-keywordurls"></a>
+
+### `g8.api.intent.keywordUrls(input)`
+
+**Keyword Urls**
+
+- HTTP: `POST /api/v1/intent/keywords/{keyword_id}/urls`
+- operationId: `keyword_urls_intent_keywords__keyword_id__urls_post` (also callable as `g8.api.call("keyword_urls_intent_keywords__keyword_id__urls_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+- ★ Hand-written: [`g8.intent.keywordUrls()`](../sdk-clients.md#g8-intent-keywordurls)
+
+URLs linked to a compete-tracking keyword (data4seo_task_results).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.keyword_id` | `string (uuid)` | yes |  |
+| `body` | `KeywordDetailRequest` | yes | Request body; fields below. |
+
+Body fields (`KeywordDetailRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.conditions` | `Array<Record<string, unknown>>` | no | Optional `[{field, operator, value}]` filter conditions. |
+| `body.limit` | `integer` | no | default `100`, min 1, max 500 |
+| `body.page` | `integer` | no | default `1`, min 1 |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.intent.keywordUrls({
+  path: { keyword_id: "00000000-0000-0000-0000-000000000000" },
+  body: {},
+});
+```
+
+---
+
+<a id="op-keywordsadd"></a>
+
+### `g8.api.intent.keywordsAdd(input)`
+
+**Keywords Add**
+
+- HTTP: `POST /api/v1/intent/keywords/add`
+- operationId: `keywords_add_intent_keywords_add_post` (also callable as `g8.api.call("keywords_add_intent_keywords_add_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Bulk-add plain compete-tracking keyword rows (web-UI "Add keywords" parity).
+
+Thin public proxy over the SAME handler the graph8 web UI's Buyer Intent >
+Keywords bulk-add uses (``POST /intent/keywords/add-keywords`` internally).
+One deliberate strictness on top of the UI path: entries are trimmed of
+leading/trailing whitespace before saving (the UI screen saves them raw).
+Everything else matches the UI path:
+
+- Keywords are stored lowercased; the response carries the stored text.
+- A keyword that already exists for this org + ``signal_type`` (and is not
+  soft-deleted) is skipped silently by the handler; this route reports it
+  as ``skipped`` with reason ``already_exists``. Soft-deleted keywords can
+  be re-added.
+- For ``signal_type='intent'`` each NEWLY created keyword fires a
+  background SERP fetch that seeds its URL set asynchronously - URLs and
+  resolved contacts/companies appear later, not in this response.
+- Unlike ``create-from-search`` this saves the plain phrase only (no
+  search seeding, no ``search_filters``); use
+  ``/keywords/{id}/filters`` afterwards to set per-keyword filters.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `KeywordsAddRequest` | yes | Request body; fields below. |
+
+Body fields (`KeywordsAddRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.keywords` | `Array<string>` | yes | 1-50 keyword phrases to add as plain compete-tracking rows. Stored lowercased. Empty / whitespace-only entries and in-request duplicates (case-insensitive, trimmed) are skipped, not saved twice. min items 1, max items 50 |
+| `body.signal_type` | `"intent" \| "jobs" \| "job_changes"` | no | Signal source discriminator, same vocabulary as the web UI: 'intent' (default, buyer-intent tracking), 'jobs', or 'job_changes'. default `"intent"` |
+
+**Returns** `ApiResponse_KeywordsAddResponse_`: the envelope `{ data: KeywordsAddResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`KeywordsAddResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created` | `Array<KeywordAddedItem>` | no | default `[]` |
+| `created_count` | `integer` | no | default `0` |
+| `skipped` | `Array<KeywordsAddSkippedItem>` | no | default `[]` |
+| `skipped_count` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.intent.keywordsAdd({ body: { keywords: ["example"] } });
+```
+
+---
+
+<a id="op-keywordscreatefromdomain"></a>
+
+### `g8.api.intent.keywordsCreateFromDomain(input)`
+
+**Keywords Create From Domain**
+
+- HTTP: `POST /api/v1/intent/keywords/create-from-domain`
+- operationId: `keywords_create_from_domain_intent_keywords_create_from_domain_post` (also callable as `g8.api.call("keywords_create_from_domain_intent_keywords_create_from_domain_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+- ★ Hand-written: [`g8.intent.createFromDomain()`](../sdk-clients.md#g8-intent-createfromdomain)
+
+One-shot compete-tracking keyword create.
+
+Under the hood:
+  1. `pages-by-domain` -> on-domain / subdomain URLs only
+  2. `contacts` -> pre-resolved people across those URLs
+  3. `save-from-search` -> persists the keyword row with both
+
+The off-domain guard is strict: every page returned from step 1 is
+re-checked against `^(.+\.)?<domain>$` before save, so nothing that
+isn't actually on the competitor's site can slip in.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `KeywordCreateFromDomainRequest` | yes | Request body; fields below. |
+
+Body fields (`KeywordCreateFromDomainRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.domain` | `string` | yes | Competitor domain to track, e.g. 'cognism.com'. min length 3, max length 253 |
+| `body.contact_limit` | `integer` | no | Max contacts to pre-resolve. default `200`, min 1, max 500 |
+| `body.page_limit` | `integer` | no | Max pages to seed from the domain. default `200`, min 1, max 500 |
+
+**Returns** `ApiResponse_KeywordCreateFromDomainResponse_`: the envelope `{ data: KeywordCreateFromDomainResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`KeywordCreateFromDomainResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `keyword` | `string` | yes |  |
+| `companies_seeded` | `integer` | no | default `0` |
+| `contacts_seeded` | `integer` | no | default `0` |
+| `keyword_id` | `string \| null` | no |  |
+| `message` | `string` | no | default `""` |
+| `off_domain_rejected` | `integer` | no | default `0` |
+| `pages_seeded` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.intent.keywordsCreateFromDomain({ body: { domain: "acme.com" } });
+```
+
+---
+
+<a id="op-keywordscreatefromsearch"></a>
+
+### `g8.api.intent.keywordsCreateFromSearch(input)`
+
+**Keywords Create From Search**
+
+- HTTP: `POST /api/v1/intent/keywords/create-from-search`
+- operationId: `keywords_create_from_search_intent_keywords_create_from_search_post` (also callable as `g8.api.call("keywords_create_from_search_intent_keywords_create_from_search_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Bulk-create compete-tracking keywords from free-text queries.
+
+The array/free-text sibling of ``create-from-domain``. For EACH keyword
+(max 10, processed sequentially) it runs:
+
+  1. ``pages/search``            - text/semantic search of the intent index
+  2. ``contacts_for_urls``       - resolve people who visited those pages
+  3. ``save_keyword_from_search``- persist the keyword + URLs + contacts
+
+Each keyword is isolated: a failure on one yields ``status="error"`` for
+that item and never fails the whole batch. Empty / whitespace-only entries
+and in-request duplicates (case-insensitive, trimmed) are ``status="skipped"``
+before any search/resolve work.
+
+NOTE - not idempotent across requests: re-posting the same keyword text in a
+LATER request replaces the prior saved row and returns a NEW ``keyword_id``
+(the underlying save is replace-on-save for an exact keyword+filters match).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `KeywordsCreateFromSearchRequest` | yes | Request body; fields below. |
+
+Body fields (`KeywordsCreateFromSearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.keywords` | `Array<string>` | yes | 1-10 free-text keyword queries. Each is searched against the intent page index, contacts/companies are resolved, and a compete-tracking keyword row is saved. Duplicates within the request (case-insensitive, trimmed) are skipped, not re-saved. min items 1, max items 10 |
+| `body.contact_limit` | `integer` | no | Max contacts to pre-resolve per keyword. default `50`, min 1, max 100 |
+| `body.page_limit` | `integer` | no | Max pages to seed per keyword. Deliberately smaller than create-from-domain's 200 default since this runs once per keyword. default `20`, min 1, max 50 |
+| `body.search_filters` | `Record<string, unknown> \| null` | no | Optional intent-search filters applied to EVERY keyword in the batch (audience, page_type, commercial_score_min, etc.). Stored verbatim on each saved keyword row so the daily resolver replays them. |
+| `body.semantic_ratio` | `number` | no | 0 = text search (default, cheapest), 1 = semantic, between = hybrid. default `0`, min 0, max 1 |
+
+**Returns** `ApiResponse_KeywordsCreateFromSearchResponse_`: the envelope `{ data: KeywordsCreateFromSearchResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`KeywordsCreateFromSearchResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created_count` | `integer` | no | default `0` |
+| `error_count` | `integer` | no | default `0` |
+| `results` | `Array<KeywordCreateFromSearchItem>` | no | default `[]` |
+| `skipped_count` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.intent.keywordsCreateFromSearch({ body: { keywords: ["example"] } });
+```
+
+---
+
+<a id="op-keywordsdelete"></a>
+
+### `g8.api.intent.keywordsDelete(input)`
+
+**Keywords Delete**
+
+- HTTP: `DELETE /api/v1/intent/keywords/{keyword_id}`
+- operationId: `keywords_delete_intent_keywords__keyword_id__delete` (also callable as `g8.api.call("keywords_delete_intent_keywords__keyword_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `intent:delete`
+- ★ Hand-written: [`g8.intent.deleteKeyword()`](../sdk-clients.md#g8-intent-deletekeyword)
+
+Soft-delete a compete-tracking keyword row.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.keyword_id` | `string (uuid)` | yes | Keyword row UUID. |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.intent.keywordsDelete({ path: { keyword_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-keywordslist"></a>
+
+### `g8.api.intent.keywordsList(input)`
+
+**Keywords List**
+
+- HTTP: `POST /api/v1/intent/keywords/list`
+- operationId: `keywords_list_intent_keywords_list_post` (also callable as `g8.api.call("keywords_list_intent_keywords_list_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+- ★ Hand-written: [`g8.intent.listKeywords()`](../sdk-clients.md#g8-intent-listkeywords)
+
+All compete-tracking keyword rows for the org.
+
+Each row carries `total_resolved_contacts` and
+`total_resolved_companies` so the caller can rank rows by actual
+compete intelligence delivered.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `KeywordsListRequest` | yes | Request body; fields below. |
+
+Body fields (`KeywordsListRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.keyword_contains` | `string \| null` | no | Case-insensitive keyword substring filter. |
+| `body.limit` | `integer` | no | default `100`, min 1, max 500 |
+| `body.page` | `integer` | no | default `1`, min 1 |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.intent.keywordsList({ body: {} });
+```
+
+---
+
+<a id="op-pagesbydomain"></a>
+
+### `g8.api.intent.pagesByDomain(input)`
+
+**Pages By Domain**
+
+- HTTP: `POST /api/v1/intent/pages-by-domain`
+- operationId: `pages_by_domain_intent_pages_by_domain_post` (also callable as `g8.api.call("pages_by_domain_intent_pages_by_domain_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+- ★ Hand-written: [`g8.intent.pagesByDomain()`](../sdk-clients.md#g8-intent-pagesbydomain)
+
+Every indexed page on a competitor domain (and its subdomains).
+
+Queries ClickHouse `intent.crawl_pages` directly via a
+`domain_root = X OR domain_root LIKE '%.X'` filter. Orders by
+`commercial_score DESC`. Primary consumer: compete-tracking keyword
+setup - avoids polluting a keyword row with news articles that only
+mention the competitor.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `PagesByDomainRequest` | yes | Request body; fields below. |
+
+Body fields (`PagesByDomainRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.domain` | `string` | yes | Competitor root domain. Subdomains auto-matched. min length 3, max length 253 |
+| `body.limit` | `integer` | no | default `200`, min 1, max 500 |
+| `body.offset` | `integer` | no | default `0`, min 0 |
+
+**Returns** `ApiResponse_PagesByDomainResponse_`: the envelope `{ data: PagesByDomainResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`PagesByDomainResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `domain` | `string` | yes |  |
+| `pages` | `Array<IntentPageItem>` | no | default `[]` |
+| `took_ms` | `integer` | no | default `0` |
+| `total_hits` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.intent.pagesByDomain({ body: { domain: "acme.com" } });
+```
+
+---
+
+<a id="op-pagescontacts"></a>
+
+### `g8.api.intent.pagesContacts(input)`
+
+**Pages Contacts**
+
+- HTTP: `POST /api/v1/intent/pages/contacts`
+- operationId: `pages_contacts_intent_pages_contacts_post` (also callable as `g8.api.call("pages_contacts_intent_pages_contacts_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+- ★ Hand-written: [`g8.intent.pageContacts()`](../sdk-clients.md#g8-intent-pagecontacts)
+
+Aggregated, deduplicated resolved contacts across a URL list.
+
+One batched HEM pull, then the 4-path identity fan-out. Used to
+pre-populate the `contacts` array on a save-from-search keyword so the
+row shows contact counts immediately (not after the daily resolver).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `PagesContactsRequest` | yes | Request body; fields below. |
+
+Body fields (`PagesContactsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.urls` | `Array<string>` | yes | min items 1, max items 200 |
+| `body.limit` | `integer` | no | default `100`, min 1, max 500 |
+| `body.mode` | `string` | no | default `"quick"` |
+| `body.offset` | `integer` | no | default `0`, min 0 |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.intent.pagesContacts({ body: { urls: ["https://example.com"] } });
+```
+
+---
+
+<a id="op-pagessearch"></a>
+
+### `g8.api.intent.pagesSearch(input)`
+
+**Pages Search**
+
+- HTTP: `POST /api/v1/intent/pages/search`
+- operationId: `pages_search_intent_pages_search_post` (also callable as `g8.api.call("pages_search_intent_pages_search_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+- ★ Hand-written: [`g8.intent.searchPages()`](../sdk-clients.md#g8-intent-searchpages)
+
+Text / semantic / hybrid search across the intent-enriched page index.
+
+Honors the same operator syntax the internal search box supports:
+`site:<domain>`, `intitle:X`, `inurl:X`, `type:blog`, `audience:b2b`,
+`-exclude`, or just a bare domain for domain-mode.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `PagesSearchRequest` | yes | Request body; fields below. |
+
+Body fields (`PagesSearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.query` | `string` | yes | min length 1, max length 500 |
+| `body.filters` | `Record<string, unknown> \| null` | no |  |
+| `body.include_visitors` | `boolean` | no | default `true` |
+| `body.limit` | `integer` | no | default `50`, min 1, max 500 |
+| `body.offset` | `integer` | no | default `0`, min 0 |
+| `body.semantic_ratio` | `number` | no | 0 = text, 1 = semantic, between = hybrid default `0`, min 0, max 1 |
+| `body.sort` | `Array<string> \| null` | no |  |
+
+**Returns** `ApiResponse_PagesSearchResponse_`: the envelope `{ data: PagesSearchResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`PagesSearchResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query` | `string` | yes |  |
+| `mode` | `string` | no | default `"text"` |
+| `pages` | `Array<IntentPageItem>` | no | default `[]` |
+| `took_ms` | `integer` | no | default `0` |
+| `total_hits` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.intent.pagesSearch({ body: { query: "example" } });
+```
+
+---
+
+<a id="op-pagesvisitorcounts"></a>
+
+### `g8.api.intent.pagesVisitorCounts(input)`
+
+**Pages Visitor Counts**
+
+- HTTP: `POST /api/v1/intent/pages/visitor-counts`
+- operationId: `pages_visitor_counts_intent_pages_visitor_counts_post` (also callable as `g8.api.call("pages_visitor_counts_intent_pages_visitor_counts_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+- ★ Hand-written: [`g8.intent.pageVisitorCounts()`](../sdk-clients.md#g8-intent-pagevisitorcounts)
+
+Batched unique-visitor count per page URL.
+
+Reads the pre-aggregated `intent.url_visitor_counts` MV first; falls
+back to the raw `intent.optimized_signals_v1` if the MV doesn't exist
+yet. Fast enough to call with thousands of URLs.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `PagesVisitorCountsRequest` | yes | Request body; fields below. |
+
+Body fields (`PagesVisitorCountsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.urls` | `Array<string>` | yes | min items 1, max items 15000 |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.intent.pagesVisitorCounts({ body: { urls: ["https://example.com"] } });
+```
+
+---
+
+<a id="op-pagesvisitors"></a>
+
+### `g8.api.intent.pagesVisitors(input)`
+
+**Pages Visitors**
+
+- HTTP: `POST /api/v1/intent/pages/visitors`
+- operationId: `pages_visitors_intent_pages_visitors_post` (also callable as `g8.api.call("pages_visitors_intent_pages_visitors_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+- ★ Hand-written: [`g8.intent.pageVisitors()`](../sdk-clients.md#g8-intent-pagevisitors)
+
+Resolve the people who visited a specific page URL.
+
+Backed by the same S1 -> S2 chain the FE drill-down uses. Returns
+HEM, profile fields (verified), and a `source` tier (verified / b2b /
+b2c / company / anonymous) so the caller can filter confidence.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `PagesVisitorsRequest` | yes | Request body; fields below. |
+
+Body fields (`PagesVisitorsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.url` | `string` | yes | Canonical PAGE_URL, e.g. 'cognism.com/pricing' (no scheme, no www). min length 1, max length 1024 |
+| `body.limit` | `integer` | no | default `50`, min 1, max 500 |
+| `body.mode` | `string` | no | 'quick' (~500ms) or 'full' (~2-3s, all paths). default `"quick"` |
+| `body.offset` | `integer` | no | default `0`, min 0 |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.intent.pagesVisitors({ body: { url: "https://example.com" } });
+```
+
+---
+
+<a id="op-urlcompanies"></a>
+
+### `g8.api.intent.urlCompanies(input)`
+
+**Url Companies**
+
+- HTTP: `POST /api/v1/intent/url-companies`
+- operationId: `url_companies_intent_url_companies_post` (also callable as `g8.api.call("url_companies_intent_url_companies_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+- ★ Hand-written: [`g8.intent.urlCompanies()`](../sdk-clients.md#g8-intent-urlcompanies)
+
+Companies whose people visited a single URL, with a B2B/B2C split.
+
+Aggregated from `{org_id}.intent_resolved`. Contact-resolved companies
+only - IP-only company resolution is a separate treatment and is not
+included here.
+
+The response shape is field-for-field identical to the main-app
+`POST /intent-search/url-companies` that backs the FE drill-down; key
+parity between the two is locked by
+`developer_api/tests/test_intent_url_companies_api.py`.
+
+Failure semantics deliberately differ from that main-app route: it
+swallows lookup errors and returns an empty result, which over this
+surface would be indistinguishable from "nobody visited". Consistent
+with its `/intent/pages/*` siblings, this raises 503 instead so a caller
+can tell a degraded backend from a genuine zero.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `UrlCompaniesRequest` | yes | Request body; fields below. |
+
+Body fields (`UrlCompaniesRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.url` | `string` | yes | Canonical page_url (no scheme, no www) |
+| `body.days` | `integer` | no | default `90`, min 1, max 365 |
+| `body.limit` | `integer` | no | default `200`, min 1, max 500 |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.intent.urlCompanies({ body: { url: "https://example.com" } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-intentpageitem"></a>
+
+### `IntentPageItem`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `audience` | `string \| null` | no |  |
+| `commercial_score` | `number \| null` | no |  |
+| `domain_root` | `string \| null` | no |  |
+| `mention_score` | `number \| null` | no |  |
+| `page_type` | `string \| null` | no |  |
+| `summary` | `string \| null` | no |  |
+| `title` | `string \| null` | no |  |
+| `url` | `string \| null` | no |  |
+
+<a id="type-keywordaddeditem"></a>
+
+### `KeywordAddedItem`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `keyword` | `string` | yes | Stored (lowercased) keyword text. |
+| `signal_type` | `string` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+
+<a id="type-keywordcreatefromsearchitem"></a>
+
+### `KeywordCreateFromSearchItem`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `keyword` | `string` | yes |  |
+| `status` | `string` | yes | 'created' \| 'skipped' \| 'error' |
+| `companies_seeded` | `integer` | no | default `0` |
+| `contacts_seeded` | `integer` | no | default `0` |
+| `error` | `string \| null` | no |  |
+| `keyword_id` | `string \| null` | no |  |
+| `pages_seeded` | `integer` | no | default `0` |
+
+<a id="type-keywordsaddskippeditem"></a>
+
+### `KeywordsAddSkippedItem`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `keyword` | `string` | yes |  |
+| `reason` | `string` | yes | 'empty' \| 'duplicate_in_request' \| 'already_exists' |