Installation

pip install topk-sdk

TopK Client

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

from topk_sdk import Client

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

# or with async client

from topk_sdk import AsyncClient

client = AsyncClient(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:

When the server requests the client to reduce its request rate, resulting in a SlowDown error.
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:

Go to the TopK Console

You can visit the console here.

Authenticate

Go to a project

Create a project or use an existing one.

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;

Get Started

Guides

Document API

Collection API

Installation

TopK Client

API Key

TopK with Vite/Webpack SSR

Get Started

Guides

Document API

Collection API

​TopK Client

​API Key

​TopK with Vite/Webpack SSR

TopK Client

API Key

TopK with Vite/Webpack SSR