Skip to main content
Get started with TopK by installing the SDK for your preferred language and setting up authentication.

​
Install the SDK

Choose your language and install the TopK SDK: 
pip install topk-sdk

​
Get your API key

Before you can use TopK, you need to obtain an API key from the TopK Console.
TopK API keys are project-specific. Each project requires its own API key.
1

Go to the TopK Console

Visit console.topk.io in your browser.
2

Sign in or create an account

Authenticate with your credentials or create a new account if you don’t have one.
3

Navigate to your project

Select an existing project or create a new one. Projects help you organize your collections and manage access.
4

Generate an API key

Click to generate a new API key for your project.
API keys can only be viewed once at creation time. Store it securely - you won’t be able to see it again.
Keep your API key secure and never commit it to version control. Use environment variables or secret management systems to store it safely.

​
Initialize the client

Once you have your API key, initialize a TopK client. You’ll need to specify both your API key and a region. 
from topk_sdk import Client

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

​
Configuration options

The client accepts additional configuration options: 
from topk_sdk import Client, RetryConfig

client = Client(
    api_key="YOUR_TOPK_API_KEY",
    region="aws-us-east-1-elastica",
    host="topk.io",  # Custom host (optional)
    https=True,  # Use HTTPS (default: True)
    retry_config=RetryConfig(
        max_retries=3,
        timeout=30000,  # milliseconds
    )
)
For a complete list of client configuration options, see the SDK reference:

​
Understanding regions

TopK clients are region-specific. You must specify a region when creating a client.Attempting to access collections or documents outside the specified region will result in a region mismatch error.
A region determines where your data is physically stored. TopK maps regions to specific cloud provider locations:
Region NameCloud ProviderLocation
aws-us-east-1-elasticaAWSN. Virginia (us-east-1)
aws-eu-central-1-monsteraAWSFrankfurt (eu-central-1)
Choose a region based on:
  • Data residency requirements - Where your data needs to be stored legally
  • Latency - Choose a region close to your users or application
  • Compliance - Specific regulatory requirements for data location
See the Regions page for more details.

​
Using with SSR frameworks

If you’re using the TopK JavaScript SDK in a server-side rendering (SSR) environment, you may need additional configuration.
If you’re using topk-js in a Vite project with SSR, configure it as an external dependency:
vite.config.ts
export default defineConfig({
  // ...
  ssr: {
    external: ["topk-js"],
  },
  optimizeDeps: {
    exclude: ["topk-js"],
  },
});
For Next.js projects, especially with App Router and Server Components, mark topk-js as external:
next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  serverExternalPackages: ["topk-js"],
};

export default nextConfig;

​
Next steps

Now that you have TopK installed and configured, you’re ready to start building:

Quickstart

Build your first search application in 5 minutes

Create a collection

Learn how to define schemas and create collections

Add documents

Insert your first documents

Query data

Search your collections with semantic and keyword search

Build docs developers (and LLMs) love

Get started for freeTalk to us