SDKs

Four SDKs are generated from the same OpenAPI document as this reference, so every operation, parameter and error you see here has a method of the same name in each of them (operationId in camelCase, snake_case or PascalCase as the language prefers).

Create a client

import { AACSearchClient } from "aacsearch";
const client = new AACSearchClient({ baseUrl: "https://api.aacsearch.com/v1", apiKey: process.env.NOVA_API_KEY! });

Search

const page = await client.documents.searchCollection({
  collectionName: "products",
  searchParameters: { q: "cordless drill", query_by: "name,brand", filter_by: "in_stock:true", per_page: 20 },
});

Results carry the platform's extensions next to the engine's fields: redirect and suggestions from search rules, query_rewrite when a zero-hit query was rescued, and found.

Stream the assistant

The streaming operation is Server-Sent Events; every SDK exposes it as an iterator of ChatChunks (sources, delta…, usage, done).

const stream = await client.assistants.streamChatCompletion({ assistantId, body: { messages: [{ role: "user", content: q }] } });
for await (const chunk of stream) if (chunk.type === "delta") process.stdout.write(chunk.delta ?? "");

Pass conversation_id from the done chunk on the next turn to keep the memory; GET …/conversations/{id} returns the history.

Events, recommendations, voice, images

await client.events.ingestEvents({ events: [{ type: "purchase", collection: "products", session_id, doc_ids: ["42"], value: 12990, currency: "RUB" }] });
const similar = await client.recommendations.getRecommendations({ collectionName: "products", model_id: "similar", object_id: "42" });
const text = await client.voice.createTranscription({ file: clip, language: "ru" });
const byPhoto = await client.media.searchByImage({ collectionName: "products", image_base64, vector_field: "image_embedding" });

Errors, retries, timeouts

Non-2xx answers raise a typed error per status — BadRequestError, UnauthorizedError, PaymentRequiredError (the wallet cannot cover an AI operation), ForbiddenError (key scope), NotFoundError, ConflictError, TooManyRequestsError (quota or per-session allowance) — each carrying the status and the JSON body. Requests are retried with backoff on 408, 429 and 5xx, honouring Retry-After; every method takes request options to change maxRetries and the timeout (60 s by default). Turn retries off for assistant turns you would rather not pay for twice.

In the browser

Use a search key (see keys and scopes) and send the visitor's X-NOVA-SESSION-ID. For a ready-made search page, autocomplete, support chat and recommendation blocks, use the aacsearch-ui package, which wraps this SDK.

Regenerating

The SDKs are Fern output, committed to the repository; fern/README.md documents the pipeline (pnpm generate, fern generate, pnpm sdk:patch) and the few things the generators cannot express.