# WonderSearch

Semantic retrieval over ingested documents and workspace collections, with corpus-native citation identities.

Canonical: https://searchsdk.dev/docs/providers/wondersearch
Markdown: https://searchsdk.dev/docs/providers/wondersearch.md

<a id="overview"></a>

## Corpus retrieval boundary

> **TypeScript reference**
> The API names, code and policy behavior in this article describe the TypeScript SDK. See [your language guide](https://searchsdk.dev/docs/sdks) for its supported surface and limits.

WonderSearch.ai and WonderSearch.com are one provider. Its native client searches a drive or workspace corpus and preserves provider document, revision, snapshot, and passage data. It is not a normalized open-web adapter.

Ingestion readiness is a prerequisite. Preserve passage snapshots and text offsets for citations. A document ID is not a public web URL. Search requires a provider Idempotency-Key; the native client does not invent one or silently resubmit ambiguous work.

Corpus scopes and native metadata filters; normalized web domain filters do not apply.

<a id="native-client"></a>

## Provider-native client

**wondersearch-native.ts · server**

```typescript
import { createWonderSearchClient } from '@belweave/search-sdk/native-wondersearch';

const apiKey = process.env.WONDERSEARCH_API_KEY;
if (!apiKey) throw new Error('WONDERSEARCH_API_KEY is required');

const client = createWonderSearchClient({ apiKey, timeoutMs: 10_000 });
const response = await client.searchDrive({
  path: { drive_id: 'your-drive-id' },
  headers: { 'Idempotency-Key': crypto.randomUUID() },
  body: { query: 'SQLite write concurrency' },
});
console.log(response.data, response.metadata);
```

Read provider data from `response.data` and sanitized transport details from `response.metadata`. Native TypeScript response types are not runtime schema validation. Preserve the operation's native response and source identities.

<a id="operations"></a>

## Native operation inventory

Methods available on this native client. Paths are relative to each operation's fixed base; a provider may use more than one origin. Eligible operations retry only when you opt into a client retry policy.

| Method | HTTP / relative path | Response / retry eligibility |
| --- | --- | --- |
| `searchDrive` | `POST /v1/drives/{drive_id}/search` | json · no automatic retry |
| `getPassage` | `GET /v1/drives/{drive_id}/passages/{passage_id}` | json · eligible |
| `getCapabilities` | `GET /v1/workspaces/{workspace_id}/capabilities` | json · eligible |
| `searchWorkspace` | `POST /v1/workspaces/{workspace_id}/search` | json · no automatic retry |
| `bootstrapAccount` | `POST /v1/account/bootstrap` | json · no automatic retry |
| `getMe` | `GET /v1/me` | json · eligible |
| `listOrganizations` | `GET /v1/organizations` | json · eligible |
| `getOrganization` | `GET /v1/organizations/{organization_id}` | json · eligible |
| `getOrganizationRaw` | `GET /v1/organizations/{organization_id}` | raw · eligible |
| `updateOrganization` | `PATCH /v1/organizations/{organization_id}` | json · no automatic retry |
| `listOrganizationMembers` | `GET /v1/organizations/{organization_id}/members` | json · eligible |
| `updateOrganizationMember` | `PATCH /v1/organizations/{organization_id}/members/{user_id}` | json · no automatic retry |
| `deleteOrganizationMember` | `DELETE /v1/organizations/{organization_id}/members/{user_id}` | json · no automatic retry |
| `listOrganizationWorkspaces` | `GET /v1/organizations/{organization_id}/workspaces` | json · eligible |
| `createOrganizationWorkspace` | `POST /v1/organizations/{organization_id}/workspaces` | json · no automatic retry |
| `getWorkspace` | `GET /v1/workspaces/{workspace_id}` | json · eligible |
| `getWorkspaceRaw` | `GET /v1/workspaces/{workspace_id}` | raw · eligible |
| `updateWorkspace` | `PATCH /v1/workspaces/{workspace_id}` | json · no automatic retry |
| `listWorkspaceInheritedMembers` | `GET /v1/workspaces/{workspace_id}/inherited-members` | json · eligible |
| `listWorkspaceMembers` | `GET /v1/workspaces/{workspace_id}/members` | json · eligible |
| `createWorkspaceMember` | `POST /v1/workspaces/{workspace_id}/members` | json · no automatic retry |
| `updateWorkspaceMember` | `PATCH /v1/workspaces/{workspace_id}/members/{user_id}` | json · no automatic retry |
| `deleteWorkspaceMember` | `DELETE /v1/workspaces/{workspace_id}/members/{user_id}` | json · no automatic retry |
| `listOrganizationInvitations` | `GET /v1/organizations/{organization_id}/invitations` | json · eligible |
| `createOrganizationInvitation` | `POST /v1/organizations/{organization_id}/invitations` | json · no automatic retry |
| `getOrganizationInvitation` | `GET /v1/organizations/{organization_id}/invitations/{invitation_id}` | json · eligible |
| `getOrganizationInvitationRaw` | `GET /v1/organizations/{organization_id}/invitations/{invitation_id}` | raw · eligible |
| `deleteOrganizationInvitation` | `DELETE /v1/organizations/{organization_id}/invitations/{invitation_id}` | json · no automatic retry |
| `resendOrganizationInvitation` | `POST /v1/organizations/{organization_id}/invitations/{invitation_id}/resend` | json · no automatic retry |
| `previewInvitation` | `POST /v1/invitations/preview` | json · no automatic retry |
| `acceptInvitation` | `POST /v1/invitations/accept` | json · no automatic retry |
| `listWorkspaceApiKeys` | `GET /v1/workspaces/{workspace_id}/api-keys` | json · eligible |
| `createWorkspaceApiKey` | `POST /v1/workspaces/{workspace_id}/api-keys` | json · no automatic retry |
| `deleteWorkspaceApiKey` | `DELETE /v1/workspaces/{workspace_id}/api-keys/{key_id}` | json · no automatic retry |
| `getWorkspaceOverview` | `GET /v1/workspaces/{workspace_id}/overview` | json · eligible |
| `getOrganizationUsage` | `GET /v1/organizations/{organization_id}/usage` | json · eligible |
| `listWorkspaceDrives` | `GET /v1/workspaces/{workspace_id}/drives` | json · eligible |
| `createWorkspaceDrive` | `POST /v1/workspaces/{workspace_id}/drives` | json · no automatic retry |
| `getDrive` | `GET /v1/drives/{drive_id}` | json · eligible |
| `getDriveRaw` | `GET /v1/drives/{drive_id}` | raw · eligible |
| `updateDrive` | `PATCH /v1/drives/{drive_id}` | json · no automatic retry |
| `deleteDrive` | `DELETE /v1/drives/{drive_id}` | json · no automatic retry |
| `listDriveFolders` | `GET /v1/drives/{drive_id}/folders` | json · eligible |
| `createDriveFolder` | `POST /v1/drives/{drive_id}/folders` | json · no automatic retry |
| `getDriveFolder` | `GET /v1/drives/{drive_id}/folders/{folder_id}` | json · eligible |
| `getDriveFolderRaw` | `GET /v1/drives/{drive_id}/folders/{folder_id}` | raw · eligible |
| `updateDriveFolder` | `PATCH /v1/drives/{drive_id}/folders/{folder_id}` | json · no automatic retry |
| `deleteDriveFolder` | `DELETE /v1/drives/{drive_id}/folders/{folder_id}` | json · no automatic retry |
| `createDriveDocument` | `POST /v1/drives/{drive_id}/documents` | json · no automatic retry |
| `listDriveDocuments` | `GET /v1/drives/{drive_id}/documents` | json · eligible |
| `getDriveDocument` | `GET /v1/drives/{drive_id}/documents/{document_id}` | json · eligible |
| `replaceDocument` | `PUT /v1/drives/{drive_id}/documents/{document_id}` | json · no automatic retry |
| `deleteDriveDocument` | `DELETE /v1/drives/{drive_id}/documents/{document_id}` | json · no automatic retry |
| `getDriveDocumentSource` | `GET /v1/drives/{drive_id}/documents/{document_id}/source` | bytes · eligible |
| `getWorkspaceDefaultDrive` | `GET /v1/workspaces/{workspace_id}/default-drive` | json · eligible |
| `getWorkspaceDefaultDriveRaw` | `GET /v1/workspaces/{workspace_id}/default-drive` | raw · eligible |
| `setDefaultDrive` | `PUT /v1/workspaces/{workspace_id}/default-drive` | json · no automatic retry |
| `getSdkContext` | `GET /v1/sdk/context` | json · eligible |
| `getDriveUploadCapabilities` | `GET /v1/drives/{drive_id}/uploads/capabilities` | json · eligible |
| `createUploadBatch` | `POST /v1/drives/{drive_id}/uploads/batch` | json · no automatic retry |
| `completeUploadBatch` | `POST /v1/drives/{drive_id}/uploads/batch/complete` | json · no automatic retry |
| `getUploadBatchStatus` | `POST /v1/drives/{drive_id}/uploads/batch/status` | json · no automatic retry |
| `createDriveUpload` | `POST /v1/drives/{drive_id}/uploads` | json · no automatic retry |
| `getDriveUpload` | `GET /v1/drives/{drive_id}/uploads/{upload_id}` | json · eligible |
| `uploadContent` | `PUT /v1/drives/{drive_id}/uploads/{upload_id}/content` | json · no automatic retry |
| `createUploadTransfer` | `POST /v1/drives/{drive_id}/uploads/{upload_id}/transfer` | json · no automatic retry |
| `completeUpload` | `POST /v1/drives/{drive_id}/uploads/{upload_id}/complete` | json · no automatic retry |
| `getWorkspaceOperation` | `GET /v1/workspaces/{workspace_id}/operations/{operation_id}` | json · eligible |
| `createImport` | `PUT /v1/drives/{drive_id}/imports/{import_id}` | json · no automatic retry |
| `getImport` | `GET /v1/drives/{drive_id}/imports/{import_id}` | json · eligible |
| `declareImportChunks` | `POST /v1/drives/{drive_id}/imports/{import_id}/chunks` | json · no automatic retry |
| `acknowledgeImportChunk` | `POST /v1/drives/{drive_id}/imports/{import_id}/chunks/{sequence}/acknowledge` | json · no automatic retry |
| `sealImport` | `POST /v1/drives/{drive_id}/imports/{import_id}/seal` | json · no automatic retry |
| `getIngestionMetrics` | `GET /v1/drives/{drive_id}/ingestion-metrics` | json · eligible |
| `getOrganizationBilling` | `GET /v1/organizations/{organization_id}/billing` | json · eligible |
| `setBillingLimits` | `POST /v1/organizations/{organization_id}/billing/limits` | json · no automatic retry |
| `getOrganizationBillingLimits` | `GET /v1/organizations/{organization_id}/billing/limits` | json · eligible |
| `getOrganizationBillingUsage` | `GET /v1/organizations/{organization_id}/billing/usage` | json · eligible |
| `createBillingPortal` | `POST /v1/organizations/{organization_id}/billing/portal` | json · no automatic retry |
| `getOrganizationBillingWallet` | `GET /v1/organizations/{organization_id}/billing/wallet` | json · eligible |
| `getOrganizationBillingActivity` | `GET /v1/organizations/{organization_id}/billing/activity` | json · eligible |
| `createOrganizationBillingPurchase` | `POST /v1/organizations/{organization_id}/billing/purchases` | json · no automatic retry |
| `getOrganizationBillingPurchase` | `GET /v1/organizations/{organization_id}/billing/purchases/{purchase_id}` | json · eligible |
| `listOrganizationBillingInvoices` | `GET /v1/organizations/{organization_id}/billing/invoices` | json · eligible |
| `getWorkspaceStorage` | `GET /v1/workspaces/{workspace_id}/storage` | json · eligible |
| `setWorkspaceStorage` | `POST /v1/workspaces/{workspace_id}/storage` | json · no automatic retry |
| `quoteWorkspaceStorage` | `POST /v1/workspaces/{workspace_id}/storage/quote` | json · no automatic retry |
| `closeImport` | `POST /v1/drives/{drive_id}/imports/{import_id}/close` | json · no automatic retry |
| `recoverImport` | `POST /v1/drives/{drive_id}/imports/{import_id}/recover` | json · no automatic retry |
| `retryImportOperation` | `POST /v1/drives/{drive_id}/imports/{import_id}/operations/{operation_id}/retry` | json · no automatic retry |
| `getAutoTopup` | `GET /v1/organizations/{organization_id}/billing/auto-topup` | json · eligible |
| `checkoutAutoTopup` | `POST /v1/organizations/{organization_id}/billing/auto-topup/checkout` | json · no automatic retry |
| `amountAutoTopup` | `POST /v1/organizations/{organization_id}/billing/auto-topup/amount` | json · no automatic retry |
| `cancelAutoTopup` | `POST /v1/organizations/{organization_id}/billing/auto-topup/cancel` | json · no automatic retry |
| `resumeAutoTopup` | `POST /v1/organizations/{organization_id}/billing/auto-topup/resume` | json · no automatic retry |

<a id="lifecycle"></a>

## Limits and operation lifecycle

- Pass `signal` and per-call `timeoutMs` on native request input when needed.
- Persist a returned job identifier before explicitly reading or polling the same job. Native clients do not automatically poll.
- SSE data is incremental provider event text. Parse and validate terminal or error events according to the provider contract; there is no reconnect or replay.
- Native operations may create, delete, ingest, or incur charges. A successful HTTP response is not proof that a remote job completed.

<a id="sources"></a>

## Official sources

Use the official reference for current schemas, account access, and operation-specific requirements.

- [Search and passage reference](https://docs.evokoa.com/wondersearch/reference/search-api)
- [Official product](https://wondersearch.ai/)

- [Native request and response reference](https://searchsdk.dev/docs/api/native-transport)
- [All providers](https://searchsdk.dev/docs/providers)