Quickstart

Prerequisites

TopK account (Sign up here)
TopK API key (Get API key here)

CLI
Python SDK
JavaScript SDK

Install CLI

brew tap topk-io/topk
brew install topk

If you don’t have Homebrew installed, you can install it here.

Authenticate

topk login

This command prompts you to either create a new API key or set an existing one.You can also provide your API key via the TOPK_API_KEY environment variable:

export TOPK_API_KEY="your-api-key"

Create a dataset

A dataset is a named container for your documents. To create a dataset, run the following command:

topk dataset create quickstart --region aws-us-east-1-elastica

The --region flag determines where your data is stored. See available regions.

Upload a file

Upload a file to your dataset:

topk upload ./report.pdf --dataset quickstart

Ask a question

topk ask "What was the total net income of Bank of America in 2024?" -d quickstart

Install Python SDK

pip install topk-sdk

Initialize the client

Setup the TopK client with your API key and region.

import os
from topk_sdk import Client

client = Client(
    api_key=os.environ["TOPK_API_KEY"],
    region=os.environ.get("TOPK_REGION", "aws-us-east-1-elastica"),
)

See available regions for a full list of supported regions.

Create a dataset

client.datasets().create("quickstart")

Upload a file

Upload a file to your dataset by providing the document ID, the path to the file, and optional metadata:

from pathlib import Path

resp = client.dataset("my-docs").upsert_file(
    "report-2024",             # document ID
    Path("./report.pdf"),      # path to file
    {"title": "Annual Report"},  # optional metadata
)

After the file has been uploaded, wait for it to be processed:

client.dataset("my-docs").wait_for_handle(resp.handle)

Ask a question

answer = client.ask("What was the total net income of Bank of America in 2024?", ["my-docs"])

print(answer)

Install JavaScript SDK

npm install topk-js

Initialize the client

import { Client } from "topk-js";

const client = new Client({
  apiKey: "your-api-key",
  region: "aws-us-east-1-elastica",
});

See available regions for a full list of supported regions.

Create a dataset

await client.datasets().create("quickstart");

Upload a file

const resp = await client.dataset("my-docs").upsertFile(
  "report-2024",    // document ID
  "./report.pdf",   // path to file
  { title: "Annual Report" },  // optional metadata
);

Wait for the file to be processed:

await client.dataset("my-docs").waitForHandle(resp.handle);

Ask a question

const answer = await client.ask("What was the total net income of Bank of America in 2024?", ["my-docs"]);

console.log(answer);

Congratulations! You’ve just ingested your first document and asked a question.

Next steps

Ingest

Learn how to upload your documents.

Ask

Run an agentic query to get grounded answers with source citations.

Search

Find the most relevant passages in your documents.

Research

Explore topics more deeply with multi-step analysis and grounded citations.

Documentation

Core Concepts

Dataset API

Next steps

Ingest

Ask

Search

Research

Documentation

Core Concepts

Dataset API

​Next steps

Ingest

Ask

Search

Research

Next steps