Installation

Install Python or JavaScript SDK

Python

pip install topk-sdk

TopK Client

To setup a TopK client, you’ll need your API key and region:

Python

from topk_sdk import Client

client = Client(api_key="YOUR_TOPK_API_KEY", region="aws-us-east-1-elastica")

Client constructor accepts the following parameters:

api_key · string · required

The API key for the project. See below for more details.

region · string · required

The region of the project. Available regions are:

• aws-us-east-1-elastica
• aws-eu-central-1-monstera

Check out the Regions page for more information.

host · string · default: "topk.io"

The host of the project.

https · boolean · default: "true"

When using a public host this should always be true. In most cases it is used for internal purposes.

retry_config · RetryConfig

The retry configuration for the client.

By default, retries occur in two situations:

1. When the server requests the client to reduce its request rate, resulting in a SlowDown error.
2. When using the query(..., lsn=N) code path.

Show properties

max_retries · number · default: "3"

The maximum number of retries to attempt. Default is 3 retries.

timeout · number · default: "30000"

The total timeout for the retry chain in milliseconds. Default is 30,000 milliseconds (30 seconds).

backoff · BackoffConfig

The backoff configuration for the client.

Show properties

base · number · default: "2"

The base for the backoff. Default is 2x backoff.

init_backoff · number · default: "100"

The initial backoff in milliseconds. Default is 100 milliseconds.

max_backoff · number · default: "10000"

The maximum backoff in milliseconds. Default is 10,000 milliseconds (10 seconds).

TopK Client is region-specific.

Attempting to access collections or documents outside the specified region will result in a region mismatch error.

API Key

TopK API key is project-specific, so you’ll need to obtain an API key for each individual project.

To obtain your API key:

1. Go to the TopK Console

   You can visit the console here.

2. Authenticate

   Log in or create your account.

3. Go to a project

   Create a project or use an existing one.

4. Generate an API key

   Store your API key in a secure location. It can be viewed only once.

TopK follows Organization > Project > Collection hierarchical structure:

TopK with Vite/Webpack SSR

If you’re using the TopK JavaScript SDK in a server-side rendering (SSR) environment, you may need to follow these steps to ensure compatibility:

Using with Vite ?

Remix, Nuxt, SvetleKit, Astro ...

If you’re using topk-js in a Vite project with server-side rendering (SSR), you may need to configure Vite to treat it as an external dependency. This ensures compatibility and prevents build-time issues related to SSR or dependency pre-bundling.

// vite.config.ts

export default defineConfig({
  // ...
  ssr: {
    external: ["topk-js"],
  },
  optimizeDeps: {
    exclude: ["topk-js"],
  },
});

Using with Webpack or Turbopack ?

Next.js

If you’re using topk-js in a Next.js project (especially with the App Router and Server Components), you may need to mark it as an external package to avoid build issues during server-side bundling.

// next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
  serverExternalPackages: ["topk-js"],
};

export default nextConfig;