Skip to main content
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:
  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.
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:
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"],
  },
});
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;
⌘I