@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/search.md

@@ -0,0 +1,866 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.search`: Search
+
+19 operations (13 read, 1 write, 1 destructive, 4 billable).
+
+4 of these also have a hand-written method (`g8.enrich`, `g8.search`), 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: [search.d.ts](search.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`deleteSavedSearch`](#op-deletesavedsearch) | `DELETE /api/v1/search/saved-searches/{query_id}` | destructive | `search:delete` | Delete Saved Search |
+| [`getAutocompleteSuggestions`](#op-getautocompletesuggestions) | `GET /api/v1/search/autocomplete` | read | `search:read` | Get Autocomplete Suggestions |
+| [`getFilterOptions`](#op-getfilteroptions) | `GET /api/v1/search/filter-options` | read | `search:read` | Get Filter Options |
+| [`getFilteredFilterOptions`](#op-getfilteredfilteroptions) | `POST /api/v1/search/filter-options` | read | `search:read` | Get Filtered Filter Options |
+| [`getSearchSignalOptions`](#op-getsearchsignaloptions) | `GET /api/v1/search/signals/options` | read | `search:read` | Get Search Signal Options |
+| [`listIntentTopics`](#op-listintenttopics) | `GET /api/v1/search/filter-options/intent-topics` | read | `search:read` | List Intent Topics |
+| [`listSavedSearches`](#op-listsavedsearches) | `GET /api/v1/search/saved-searches` | read | `search:read` | List Saved Searches |
+| [`listWorkspaceSearchSections`](#op-listworkspacesearchsections) | `GET /api/v1/search/workspace/sections` | read | `search:read` | List Workspace Search Sections |
+| [`previewSearchSignal`](#op-previewsearchsignal) | `POST /api/v1/search/signals/preview` | read | `search:read` | Preview Search Signal |
+| [`saveCompanySearch`](#op-savecompanysearch) ★ | `POST /api/v1/search/companies/save` | billable | `search:run` | Save Company Search |
+| [`saveContactSearch`](#op-savecontactsearch) ★ | `POST /api/v1/search/contacts/save` | billable | `search:run` | Save Contact Search |
+| [`saveSearch`](#op-savesearch) | `POST /api/v1/search/saved-searches` | write | `search:write` | Save Search |
+| [`searchCompanies`](#op-searchcompanies) ★ | `POST /api/v1/search/companies` | billable | `search:run` | Search Companies |
+| [`searchContacts`](#op-searchcontacts) ★ | `POST /api/v1/search/contacts` | billable | `search:run` | Search Contacts |
+| [`searchCrmEntities`](#op-searchcrmentities) | `GET /api/v1/search/entities` | read | `search:read` | Search Crm Entities |
+| [`searchWorkspaceDocuments`](#op-searchworkspacedocuments) | `POST /api/v1/search/workspace` | read | `search:read` | Search Workspace Documents |
+| [`searchWorkspaceGlobal`](#op-searchworkspaceglobal) | `GET /api/v1/search/global` | read | `search:read` | Search Workspace Global |
+| [`suggestSearchSignalTech`](#op-suggestsearchsignaltech) | `GET /api/v1/search/signals/tech` | read | `search:read` | Suggest Search Signal Tech |
+| [`suggestWorkspaceSearch`](#op-suggestworkspacesearch) | `POST /api/v1/search/workspace/suggest` | read | `search:read` | Suggest Workspace Search |
+
+---
+
+<a id="op-deletesavedsearch"></a>
+
+### `g8.api.search.deleteSavedSearch(input)`
+
+**Delete Saved Search**
+
+- HTTP: `DELETE /api/v1/search/saved-searches/{query_id}`
+- operationId: `delete_saved_search_search_saved_searches__query_id__delete` (also callable as `g8.api.call("delete_saved_search_search_saved_searches__query_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `search:delete`
+
+Delete a saved search.
+
+SOFT: the row is marked deleted rather than removed, and nothing that was
+ever found by it is touched. Someone else's saved search is a 404, not a
+403, for the same reason the write above is.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.query_id` | `integer` | yes | Saved-search id. |
+
+**Returns** `ApiResponse_SearchDiscoveryPayload_`: the envelope `{ data: SearchDiscoveryPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.search.deleteSavedSearch({ path: { query_id: 123 } });
+```
+
+---
+
+<a id="op-getautocompletesuggestions"></a>
+
+### `g8.api.search.getAutocompleteSuggestions(input)`
+
+**Get Autocomplete Suggestions**
+
+- HTTP: `GET /api/v1/search/autocomplete`
+- operationId: `get_autocomplete_suggestions_search_autocomplete_get` (also callable as `g8.api.call("get_autocomplete_suggestions_search_autocomplete_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `search:read`
+
+Type-ahead over one field's values.
+
+The counterpart to `filter-options` for fields whose value set is too large
+to enumerate - company name and domain especially, where the backend also
+expands domains (`amazon` matches `amazon.com`) and ranks by company score
+rather than alphabetically.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.resource` | `"contacts" \| "companies"` | yes | Which vocabulary `field` is in. |
+| `query.field` | `string` | yes | Developer field name to search within. |
+| `query.value` | `string` | yes | What the person has typed so far. |
+| `query.size` | `integer` | no | How many suggestions to return. default `5` |
+
+**Returns** `ApiResponse_SearchDiscoveryPayload_`: the envelope `{ data: SearchDiscoveryPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.search.getAutocompleteSuggestions({
+  query: { resource: "contacts", field: "example", value: "example" },
+});
+```
+
+---
+
+<a id="op-getfilteroptions"></a>
+
+### `g8.api.search.getFilterOptions(input)`
+
+**Get Filter Options**
+
+- HTTP: `GET /api/v1/search/filter-options`
+- operationId: `get_filter_options_search_filter_options_get` (also callable as `g8.api.call("get_filter_options_search_filter_options_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `search:read`
+
+Every distinct value a field holds, across the whole open-data index.
+
+Read this BEFORE writing a filter. The `id` of each option is exactly what
+`POST /search/{resource}` expects as a filter value, so the two can be
+chained without any guessing in between.
+
+Cached server-side, so repeated calls are cheap. It does not consume
+credits.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.resource` | `"contacts" \| "companies"` | yes | Which vocabulary the field names are in. |
+| `query.fields` | `Array<string>` | yes | Developer field names, REPEATABLE (`?fields=company_industry&fields=seniority_level`). The same names `POST /search/{resource}` takes. |
+
+**Returns** `ApiResponse_dict_str__list_FilterOptionItem___`: the envelope `{ data: Record<string, Array<FilterOptionItem>>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.search.getFilterOptions({ query: { resource: "contacts", fields: ["example"] } });
+```
+
+---
+
+<a id="op-getfilteredfilteroptions"></a>
+
+### `g8.api.search.getFilteredFilterOptions(input)`
+
+**Get Filtered Filter Options**
+
+- HTTP: `POST /api/v1/search/filter-options`
+- operationId: `get_filtered_filter_options_search_filter_options_post` (also callable as `g8.api.call("get_filtered_filter_options_search_filter_options_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `search:read`
+
+The same values, but only those present in a SUBSET of the index.
+
+The difference matters: `GET /search/filter-options` answers "what
+industries exist", this answers "what industries exist among companies in
+Spain". Building a dependent filter off the unfiltered list offers the
+caller values that cannot return a single row once the other filters are
+applied.
+
+`filters` must contain at least one condition, which is the same refusal
+`POST /search/contacts` makes - an unfiltered request scans the entire
+open-data index.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `FilterOptionsRequest` | yes | Request body; fields below. |
+
+Body fields (`FilterOptionsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.fields` | `Array<string>` | yes | Developer field names, as used by `POST /search/{resource}`. min items 1 |
+| `body.resource` | `"contacts" \| "companies"` | yes | Which index the field names belong to. Decides the vocabulary. |
+| `body.filters` | `Array<SearchFilter>` | no | Filter conditions (AND logic) |
+| `body.limit` | `integer` | no | Results per page (max 100) default `25`, min 1, max 100 |
+| `body.page` | `integer` | no | Page number (1-indexed) default `1`, min 1, max 100 |
+
+**Returns** `ApiResponse_dict_str__list_FilterOptionItem___`: the envelope `{ data: Record<string, Array<FilterOptionItem>>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.search.getFilteredFilterOptions({ body: { fields: ["example"], resource: "contacts" } });
+```
+
+---
+
+<a id="op-getsearchsignaloptions"></a>
+
+### `g8.api.search.getSearchSignalOptions(input?)`
+
+**Get Search Signal Options**
+
+- HTTP: `GET /api/v1/search/signals/options`
+- operationId: `get_search_signal_options_search_signals_options_get` (also callable as `g8.api.call("get_search_signal_options_search_signals_options_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `search:read`
+
+Company categories, detected technologies and data horizons for signal filters.
+
+**Input**: none.
+
+**Returns** `ApiResponse_WorkspaceSearchPayload_`: the envelope `{ data: WorkspaceSearchPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.search.getSearchSignalOptions();
+```
+
+---
+
+<a id="op-listintenttopics"></a>
+
+### `g8.api.search.listIntentTopics(input?)`
+
+**List Intent Topics**
+
+- HTTP: `GET /api/v1/search/filter-options/intent-topics`
+- operationId: `list_intent_topics_search_filter_options_intent_topics_get` (also callable as `g8.api.call("list_intent_topics_search_filter_options_intent_topics_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `search:read`
+
+The intent topics a buying-intent filter can name.
+
+Topics carry their own numeric ids rather than the string ids the other
+filter options use, so this is a separate read rather than another entry
+in `filter-options`.
+
+**Input**: none.
+
+**Returns** `ApiResponse_list_`: the envelope `{ data: Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.search.listIntentTopics();
+```
+
+---
+
+<a id="op-listsavedsearches"></a>
+
+### `g8.api.search.listSavedSearches(input?)`
+
+**List Saved Searches**
+
+- HTTP: `GET /api/v1/search/saved-searches`
+- operationId: `list_saved_searches_search_saved_searches_get` (also callable as `g8.api.call("list_saved_searches_search_saved_searches_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `search:read`
+
+Saved searches belonging to the KEY'S OWN identity.
+
+Scoped server-side to one identity rather than to the organisation, exactly
+as the in-app route is - so this lists what the key itself saved, not what
+the whole team saved. A personal key sees the minting user's saved
+searches; an organisation key has no person behind it and sees only what
+that credential saved through this API.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.scope` | `string \| null` | no | Only saved searches over this resource, e.g. `contacts`. |
+
+**Returns** `ApiResponse_list_`: the envelope `{ data: Array<unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.search.listSavedSearches();
+```
+
+---
+
+<a id="op-listworkspacesearchsections"></a>
+
+### `g8.api.search.listWorkspaceSearchSections(input?)`
+
+**List Workspace Search Sections**
+
+- HTTP: `GET /api/v1/search/workspace/sections`
+- operationId: `list_workspace_search_sections_search_workspace_sections_get` (also callable as `g8.api.call("list_workspace_search_sections_search_workspace_sections_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `search:read`
+
+The sections workspace search can be filtered to.
+
+**Input**: none.
+
+**Returns** `ApiResponse_WorkspaceSearchListPayload_`: the envelope `{ data: WorkspaceSearchListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WorkspaceSearchListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.search.listWorkspaceSearchSections();
+```
+
+---
+
+<a id="op-previewsearchsignal"></a>
+
+### `g8.api.search.previewSearchSignal(input)`
+
+**Preview Search Signal**
+
+- HTTP: `POST /api/v1/search/signals/preview`
+- operationId: `preview_search_signal_search_signals_preview_post` (also callable as `g8.api.call("preview_search_signal_search_signals_preview_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `search:read`
+
+How many companies one signal matches on its own, before any other filter.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SearchSignalFilter` | yes | Request body; fields below. |
+
+Body fields (`SearchSignalFilter`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.type` | `"hiring" \| "tech" \| "company_type" \| "describes" \| "lookalike" \| "new_in_role"` | yes |  |
+| `body.categories` | `Array<string>` | no | company_type: category ids. |
+| `body.days` | `integer` | no | hiring / new_in_role: look-back window. default `30`, min 1, max 730 |
+| `body.domains` | `Array<string>` | no | lookalike: seed company domains. |
+| `body.exclude_staffing` | `boolean` | no | default `true` |
+| `body.facet` | `"what" \| "sells" \| "serves"` | no | default `"what"` |
+| `body.match` | `"any" \| "all"` | no | default `"any"` |
+| `body.min_roles` | `integer` | no | default `1`, min 1, max 100 |
+| `body.negate` | `boolean` | no | Match companies WITHOUT the signal (hiring, tech, company_type). default `false` |
+| `body.roles` | `Array<string>` | no | hiring: role titles. |
+| `body.status` | `"new" \| "open"` | no | default `"new"` |
+| `body.techs` | `Array<string>` | no | tech: technologies. |
+| `body.text` | `string` | no | describes: what the companies do. default `""` |
+| `body.top_k` | `integer` | no | default `300`, min 10, max 5000 |
+
+**Returns** `ApiResponse_WorkspaceSearchPayload_`: the envelope `{ data: WorkspaceSearchPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.search.previewSearchSignal({ body: { type: "hiring" } });
+```
+
+---
+
+<a id="op-savecompanysearch"></a>
+
+### `g8.api.search.saveCompanySearch(input)`
+
+**Save Company Search**
+
+- HTTP: `POST /api/v1/search/companies/save`
+- operationId: `save_company_search_search_companies_save_post` (also callable as `g8.api.call("save_company_search_search_companies_save_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `search:run`
+- ★ Hand-written: [`g8.search.saveCompanies()`](../sdk-clients.md#g8-search-savecompanies)
+
+Search companies and save matching results to a new list.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SearchSaveRequest` | yes | Request body; fields below. |
+
+Body fields (`SearchSaveRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.list_title` | `string` | yes | Title for the new list |
+| `body.filters` | `Array<SearchFilter>` | no | Filter conditions (AND logic) |
+| `body.limit` | `integer` | no | Results per page (max 100) default `25`, min 1, max 100 |
+| `body.max_results` | `integer` | no | Maximum results to save (max 10,000) default `1000`, min 1, max 10000 |
+| `body.page` | `integer` | no | Page number (1-indexed) default `1`, min 1, max 100 |
+
+**Returns** `ApiResponse_SearchSaveResponse_`: the envelope `{ data: SearchSaveResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SearchSaveResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `estimated_total` | `integer` | yes |  |
+| `list_id` | `integer` | yes |  |
+| `list_title` | `string` | yes |  |
+| `status` | `string` | no | default `"processing"` |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.search.saveCompanySearch({ body: { list_title: "Example" } });
+```
+
+---
+
+<a id="op-savecontactsearch"></a>
+
+### `g8.api.search.saveContactSearch(input)`
+
+**Save Contact Search**
+
+- HTTP: `POST /api/v1/search/contacts/save`
+- operationId: `save_contact_search_search_contacts_save_post` (also callable as `g8.api.call("save_contact_search_search_contacts_save_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `search:run`
+- ★ Hand-written: [`g8.search.saveContacts()`](../sdk-clients.md#g8-search-savecontacts)
+
+Search protected contact data and save matching results to a new list.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SearchSaveRequest` | yes | Request body; fields below. |
+
+Body fields (`SearchSaveRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.list_title` | `string` | yes | Title for the new list |
+| `body.filters` | `Array<SearchFilter>` | no | Filter conditions (AND logic) |
+| `body.limit` | `integer` | no | Results per page (max 100) default `25`, min 1, max 100 |
+| `body.max_results` | `integer` | no | Maximum results to save (max 10,000) default `1000`, min 1, max 10000 |
+| `body.page` | `integer` | no | Page number (1-indexed) default `1`, min 1, max 100 |
+
+**Returns** `ApiResponse_SearchSaveResponse_`: the envelope `{ data: SearchSaveResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SearchSaveResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `estimated_total` | `integer` | yes |  |
+| `list_id` | `integer` | yes |  |
+| `list_title` | `string` | yes |  |
+| `status` | `string` | no | default `"processing"` |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.search.saveContactSearch({ body: { list_title: "Example" } });
+```
+
+---
+
+<a id="op-savesearch"></a>
+
+### `g8.api.search.saveSearch(input)`
+
+**Save Search**
+
+- HTTP: `POST /api/v1/search/saved-searches`
+- operationId: `save_search_search_saved_searches_post` (also callable as `g8.api.call("save_search_search_saved_searches_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `search:write`
+
+Store a search so it can be run again.
+
+Sending `id` REPLACES that saved search rather than creating a second one -
+which is why a caller looping over a list should send the id back, not omit
+it. A saved search belonging to someone else comes back as a 404 rather
+than a 403, so a guessed id cannot confirm that it exists.
+
+`icp_query` is stored verbatim and is not interpreted here.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SaveSearchRequest` | yes | Request body; fields below. |
+
+Body fields (`SaveSearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.icp_query` | `Record<string, unknown>` | yes | The search itself. Opaque and round-tripped as-is. |
+| `body.scope` | `string` | yes | What the saved search is over - `contacts` or `companies` today. Deliberately a free string rather than a closed enum, matching the app, which is designed to add more. min length 1, max length 64 |
+| `body.title` | `string` | yes | min length 1, max length 255 |
+| `body.id` | `integer \| null` | no | Send the id of an existing saved search to REPLACE it. |
+
+**Returns** `ApiResponse_SearchDiscoveryPayload_`: the envelope `{ data: SearchDiscoveryPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.search.saveSearch({ body: { icp_query: {}, scope: "example", title: "Example" } });
+```
+
+---
+
+<a id="op-searchcompanies"></a>
+
+### `g8.api.search.searchCompanies(input)`
+
+**Search Companies**
+
+- HTTP: `POST /api/v1/search/companies`
+- operationId: `search_companies_search_companies_post` (also callable as `g8.api.call("search_companies_search_companies_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `search:run`
+- ★ Hand-written: [`g8.search.companies()`](../sdk-clients.md#g8-search-companies)
+
+Search open company data with the org's deliverability policy applied.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SearchRequest` | yes | Request body; fields below. |
+
+Body fields (`SearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.filters` | `Array<SearchFilter>` | no | Filter conditions (AND logic) |
+| `body.limit` | `integer` | no | Results per page (max 100) default `25`, min 1, max 100 |
+| `body.page` | `integer` | no | Page number (1-indexed) default `1`, min 1, max 100 |
+
+**Returns** `ApiResponse_list_SearchCompanyItem__`: the envelope `{ data: Array<SearchCompanyItem>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SearchCompanyItem` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `address` | `string \| null` | no |  |
+| `city` | `string \| null` | no |  |
+| `country` | `string \| null` | no |  |
+| `crunchbase_url` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `domain` | `string \| null` | no |  |
+| `employee_count` | `string \| null` | no |  |
+| `facebook_url` | `string \| null` | no |  |
+| `founded_year` | `integer \| null` | no |  |
+| `industry` | `string \| null` | no |  |
+| `industry_group` | `string \| null` | no |  |
+| `linkedin_followers` | `string \| null` | no |  |
+| `linkedin_url` | `string \| null` | no |  |
+| `logo_url` | `string \| null` | no |  |
+| `name` | `string \| null` | no |  |
+| `phone` | `string \| null` | no |  |
+| `revenue` | `string \| null` | no |  |
+| `state` | `string \| null` | no |  |
+| `twitter_url` | `string \| null` | no |  |
+| `website` | `string \| null` | no |  |
+| `zip` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.search.searchCompanies({ body: {} });
+```
+
+---
+
+<a id="op-searchcontacts"></a>
+
+### `g8.api.search.searchContacts(input)`
+
+**Search Contacts**
+
+- HTTP: `POST /api/v1/search/contacts`
+- operationId: `search_contacts_search_contacts_post` (also callable as `g8.api.call("search_contacts_search_contacts_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `search:run`
+- ★ Hand-written: [`g8.enrich.search()`](../sdk-clients.md#g8-enrich-search), [`g8.search.contacts()`](../sdk-clients.md#g8-search-contacts)
+
+Search open contact data with the org's deliverability policy applied.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SearchRequest` | yes | Request body; fields below. |
+
+Body fields (`SearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.filters` | `Array<SearchFilter>` | no | Filter conditions (AND logic) |
+| `body.limit` | `integer` | no | Results per page (max 100) default `25`, min 1, max 100 |
+| `body.page` | `integer` | no | Page number (1-indexed) default `1`, min 1, max 100 |
+
+**Returns** `ApiResponse_list_SearchContactItem__`: the envelope `{ data: Array<SearchContactItem>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SearchContactItem` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `city` | `string \| null` | no |  |
+| `company_country` | `string \| null` | no |  |
+| `company_domain` | `string \| null` | no |  |
+| `company_employee_count` | `string \| null` | no |  |
+| `company_industry` | `string \| null` | no |  |
+| `company_name` | `string \| null` | no |  |
+| `confidence_score` | `integer \| null` | no |  |
+| `country` | `string \| null` | no |  |
+| `direct_phone` | `string \| null` | no |  |
+| `first_name` | `string \| null` | no |  |
+| `job_department` | `string \| null` | no |  |
+| `job_title` | `string \| null` | no |  |
+| `last_name` | `string \| null` | no |  |
+| `linkedin_headline` | `string \| null` | no |  |
+| `linkedin_url` | `string \| null` | no |  |
+| `middle_name` | `string \| null` | no |  |
+| `mobile_phone` | `string \| null` | no |  |
+| `personal_emails` | `string \| null` | no |  |
+| `role` | `string \| null` | no |  |
+| `seniority_level` | `string \| null` | no |  |
+| `state` | `string \| null` | no |  |
+| `work_email` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.search.searchContacts({ body: {} });
+```
+
+---
+
+<a id="op-searchcrmentities"></a>
+
+### `g8.api.search.searchCrmEntities(input)`
+
+**Search Crm Entities**
+
+- HTTP: `GET /api/v1/search/entities`
+- operationId: `search_crm_entities_search_entities_get` (also callable as `g8.api.call("search_crm_entities_search_entities_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `search:read`
+
+Companies, contacts and deals by name, limited to what this key may see.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.q` | `string` | yes |  |
+| `query.types` | `string \| null` | no | Comma-separated: companies,contacts,deals. |
+| `query.lifecycle` | `string \| null` | no | Only records in this lifecycle stage. |
+| `query.limit` | `integer` | no | Results per record type. default `10` |
+
+**Returns** `ApiResponse_WorkspaceSearchPayload_`: the envelope `{ data: WorkspaceSearchPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.search.searchCrmEntities({ query: { q: "example" } });
+```
+
+---
+
+<a id="op-searchworkspacedocuments"></a>
+
+### `g8.api.search.searchWorkspaceDocuments(input)`
+
+**Search Workspace Documents**
+
+- HTTP: `POST /api/v1/search/workspace`
+- operationId: `search_workspace_documents_search_workspace_post` (also callable as `g8.api.call("search_workspace_documents_search_workspace_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `search:read`
+
+Search Studio's documents, intelligence and research.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `WorkspaceSearchRequest` | yes | Request body; fields below. |
+
+Body fields (`WorkspaceSearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.query` | `string` | yes |  |
+| `body.filters` | `Record<string, unknown> \| null` | no |  |
+| `body.k` | `integer` | no | How many results. default `20` |
+| `body.search_type` | `"semantic" \| "exact" \| "hybrid" \| "auto"` | no | `auto` picks keyword or semantic from the wording of the query. default `"auto"` |
+
+**Returns** `ApiResponse_WorkspaceSearchPayload_`: the envelope `{ data: WorkspaceSearchPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.search.searchWorkspaceDocuments({ body: { query: "example" } });
+```
+
+---
+
+<a id="op-searchworkspaceglobal"></a>
+
+### `g8.api.search.searchWorkspaceGlobal(input)`
+
+**Search Workspace Global**
+
+- HTTP: `GET /api/v1/search/global`
+- operationId: `search_workspace_global_search_global_get` (also callable as `g8.api.call("search_workspace_global_search_global_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `search:read`
+
+One query across companies, people, campaigns, deals and documents.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.q` | `string` | yes |  |
+| `query.limit` | `integer` | no | Results per category. default `5` |
+
+**Returns** `ApiResponse_WorkspaceSearchPayload_`: the envelope `{ data: WorkspaceSearchPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.search.searchWorkspaceGlobal({ query: { q: "example" } });
+```
+
+---
+
+<a id="op-suggestsearchsignaltech"></a>
+
+### `g8.api.search.suggestSearchSignalTech(input)`
+
+**Suggest Search Signal Tech**
+
+- HTTP: `GET /api/v1/search/signals/tech`
+- operationId: `suggest_search_signal_tech_search_signals_tech_get` (also callable as `g8.api.call("suggest_search_signal_tech_search_signals_tech_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `search:read`
+
+Technologies matching a partial name, with how many companies use each.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.q` | `string` | yes |  |
+
+**Returns** `ApiResponse_WorkspaceSearchListPayload_`: the envelope `{ data: WorkspaceSearchListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`WorkspaceSearchListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.search.suggestSearchSignalTech({ query: { q: "example" } });
+```
+
+---
+
+<a id="op-suggestworkspacesearch"></a>
+
+### `g8.api.search.suggestWorkspaceSearch(input)`
+
+**Suggest Workspace Search**
+
+- HTTP: `POST /api/v1/search/workspace/suggest`
+- operationId: `suggest_workspace_search_search_workspace_suggest_post` (also callable as `g8.api.call("suggest_workspace_search_search_workspace_suggest_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `search:read`
+
+Completions for a partial workspace query.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.query` | `string` | yes | What has been typed so far. |
+
+**Returns** `ApiResponse_WorkspaceSearchPayload_`: the envelope `{ data: WorkspaceSearchPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.search.suggestWorkspaceSearch({ query: { query: "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-searchfilter"></a>
+
+### `SearchFilter`
+
+A single filter condition.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `field` | `string` | yes | Field name to filter on (e.g., 'job_title', 'country', 'industry') |
+| `operator` | `SearchOperator` | yes | Filter operator |
+| `value` | `Array<unknown>` | no | Filter values |