> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

TopK is a **hybrid retrieval engine** built on object storage for **10x lower cost** and **massive scale**. It supports dense/sparse vector search, multi-vector retrieval, powerful filtering, custom ranking, and managed inference in one API.

For unstructured document search use cases, we provide a datasets abstraction that allows you to [ingest](/datasets/ingest) files, [search](/datasets/search), and [get answers](/datasets/ask) from your private documents. Connect your data to agents using our [CLI](/cli) or [MCP](/mcp-server) server.

## Get Started

<Info>
  **Prerequisites**

  * TopK account ([Sign up here](https://console.topk.io/login))
  * TopK API key ([Get an API key here](https://console.topk.io/api-key))
</Info>

### Hybrid Search

Simple example to get you started with TopK. Check out our [guides](/guides) for more complex examples.

<Tabs>
  <Tab title="Python SDK" icon="https://mintcdn.com/topk/8NBkS0nek3e9o6Vi/icons/python.svg?fit=max&auto=format&n=8NBkS0nek3e9o6Vi&q=85&s=97cbee7891538170fd752e1afbc98095" width="128" height="128" data-path="icons/python.svg">
    <Steps>
      <Step title="Install Python SDK">
        <CodeGroup>
          ```bash pip theme={null}
          pip install topk-sdk
          ```

          ```bash uv theme={null}
          uv add topk-sdk
          ```
        </CodeGroup>
      </Step>

      <Step title="Initialize the client">
        Setup the TopK client with your API key and region.

        <CodeGroup>
          ```python Sync theme={null}
          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"),
          )
          ```

          ```python Async theme={null}
          import os
          from topk_sdk import AsyncClient

          client = AsyncClient(
              api_key=os.environ["TOPK_API_KEY"],
              region=os.environ.get("TOPK_REGION", "aws-us-east-1-elastica"),
          )
          ```
        </CodeGroup>

        <Info>See [available regions](/regions) for a full list of supported regions.</Info>
      </Step>

      <Step title="Create a collection">
        <CodeGroup>
          ```python Sync theme={null}
          client.collections().create(
            "quickstart",
            schema={
              "title": text().required().index(keyword_index()),
              "content": text().index(semantic_index()),
            }
          )
          ```

          ```python Async theme={null}
          await client.collections().create(
            "quickstart",
            schema={
              "title": text().required().index(keyword_index()),
              "content": text().index(semantic_index()),
            }
          )
          ```
        </CodeGroup>
      </Step>

      <Step title="Upsert documents">
        <CodeGroup>
          ```python Sync theme={null}
          client.collection("quickstart").upsert([
            {
                "_id": "1",
                "title": "Catcher in the Rye",
                "content": "IF YOU REALLY WANT TO HEAR about it, the first thing you'll probably want to know is ...",
                "author": "J.D. Salinger",
                "year": 1951,
            },
            {
                "_id": "2",
                "title": "1984",
                "content": "It was a bright cold day in April, and the clocks were striking thirteen. Winston Smith, ...",
                "author": "George Orwell",
                "year": 1949,
            },
            ...
          ])
          ```

          ```python Async theme={null}
          await client.collection("quickstart").upsert([
            {
                "_id": "1",
                "title": "Catcher in the Rye",
                "content": "IF YOU REALLY WANT TO HEAR about it, the first thing you'll probably want to know is ...",
                "author": "J.D. Salinger",
                "rating": 3.8
            },
            {
                "_id": "2",
                "title": "1984",
                "content": "It was a bright cold day in April, and the clocks were striking thirteen. Winston Smith, ...",
                "author": "George Orwell",
                "rating": 4.7
            },
            ...
          ])
          ```
        </CodeGroup>
      </Step>

      <Step title="Query indexed data">
        <CodeGroup>
          ```python Sync theme={null}
          from topk_sdk.query import select, field, fn

          client.collection("quickstart").query(
            select(
              # Select document fields to return
              "_id", "title", "author",
              # Compute semantic similarity of content field with the query
              similarity_score = fn.semantic_similarity(
                "content",
                "What is the meaning of life?",
              )
            )
            # Filter documents by metadata
            .filter(field("rating") >= 3.0)
            # Rank using the computed similarity score and rating
            .sort(field("rating") * field("similarity_score"), asc=False)
            # Get top 10 highest ranked documents
            .limit(10)
          )
          ```

          ```python Async theme={null}
          from topk_sdk.query import select, field, fn

          await client.collection("quickstart").query(
            select(
              # Select document fields to return
              "_id", "title", "author",
              # Compute semantic similarity of content field with the query
              similarity_score = fn.semantic_similarity(
                "content",
                "What is the meaning of life?",
              )
            )
            # Filter documents by metadata
            .filter(field("rating") >= 3.0)
            # Rank using the computed similarity score and rating
            .sort(field("rating") * field("similarity_score"), asc=False)
            # Get top 10 highest ranked documents
            .limit(10)
          )
          ```
        </CodeGroup>

        <Note>
          To learn more about how to use the Python SDK, see the [Python SDK documentation](/sdk/topk-py).
        </Note>
      </Step>
    </Steps>
  </Tab>

  <Tab title="JavaScript SDK" icon="https://mintcdn.com/topk/8NBkS0nek3e9o6Vi/icons/js.svg?fit=max&auto=format&n=8NBkS0nek3e9o6Vi&q=85&s=7642cf18b45f52a70f141214b3d0eca1" width="24" height="24" data-path="icons/js.svg">
    <Steps>
      <Step title="Install JavaScript SDK">
        <CodeGroup>
          ```bash npm theme={null}
          npm install topk-js
          ```

          ```bash yarn theme={null}
          yarn add topk-js
          ```

          ```bash pnpm theme={null}
          pnpm add topk-js
          ```
        </CodeGroup>
      </Step>

      <Step title="Initialize the client">
        Setup the TopK client with your API key and region.

        ```typescript theme={null}
        import { Client } from "topk-js";

        const client = new Client({
          apiKey: process.env.TOPK_API_KEY!,
          region: process.env.TOPK_REGION ?? "aws-us-east-1-elastica",
        });
        ```

        <Info>See [available regions](/regions) for a full list of supported regions.</Info>
      </Step>

      <Step title="Create a collection">
        ```typescript theme={null}
        import { text, keywordIndex, semanticIndex } from "topk-js/schema";

        await client.collections().create("quickstart", {
          title: text().required().index(keywordIndex()),
          content: text().index(semanticIndex()),
        });
        ```
      </Step>

      <Step title="Upsert documents">
        ```typescript theme={null}
        await client.collection("quickstart").upsert([
          {
            _id: "1",
            title: "Catcher in the Rye",
            content: "IF YOU REALLY WANT TO HEAR about it, the first thing you'll probably want to know is ...",
            author: "J.D. Salinger",
            rating: 3.8,
          },
          {
            _id: "2",
            title: "1984",
            content: "It was a bright cold day in April, and the clocks were striking thirteen. Winston Smith, ...",
            author: "George Orwell",
            rating: 4.7,
          },
          // ...
        ]);
        ```
      </Step>

      <Step title="Query indexed data">
        ```typescript theme={null}
        import { select, field, fn } from "topk-js/query";

        await client.collection("quickstart").query(
          select({
            title: field("title"),
            author: field("author"),
            // Compute semantic similarity of content field with the query
            similarity_score: fn.semanticSimilarity(
              "content",
              "What is the meaning of life?",
            ),
          })
          // Filter documents by metadata
          .filter(field("rating").gte(3.0))
          // Rank using the computed similarity score and rating
          .sort(field("rating").mul(field("similarity_score")), false)
          // Get top 10 highest ranked documents
          .limit(10)
        );
        ```

        <Note>
          To learn more about how to use the JavaScript SDK, see the [JavaScript SDK documentation](/sdk/topk-js).
        </Note>
      </Step>
    </Steps>
  </Tab>

  <Tab title="SQL" icon="database">
    <Steps>
      <Step title="Connect">
        Connect using any PostgreSQL client. Use your API key as the password.

        ```bash theme={null}
        psql "host=<region>.sql.topk.io port=5432 user=topk password=$TOPK_API_KEY dbname=topk"
        ```
      </Step>

      <Step title="Create a collection">
        ```sql theme={null}
        CREATE TABLE quickstart (
          title   TEXT NOT NULL INDEX keyword_index(),
          content TEXT          INDEX semantic_index(),
          rating  FLOAT
        );
        ```
      </Step>

      <Step title="Upsert documents">
        ```sql theme={null}
        INSERT INTO quickstart (_id, title, content, author, rating)
        VALUES
          ('1', 'Catcher in the Rye',
           'IF YOU REALLY WANT TO HEAR about it, the first thing you''ll probably want to know is ...',
           'J.D. Salinger', 3.8),
          ('2', '1984',
           'It was a bright cold day in April, and the clocks were striking thirteen. Winston Smith, ...',
           'George Orwell', 4.7);
        ```
      </Step>

      <Step title="Query indexed data">
        ```sql theme={null}
        SELECT
          _id,
          title,
          semantic_similarity(content, 'What is the meaning of life?') AS similarity_score
        FROM quickstart
        WHERE rating >= 3.0
        ORDER BY similarity_score * rating DESC
        LIMIT 10;
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

### Document Search

<Tabs>
  <Tab title="CLI" icon="terminal">
    <Steps>
      <Step title="Install CLI">
        ```bash theme={null}
        brew tap topk-io/topk
        brew install topk
        ```

        <Tip>If you don't have Homebrew installed, you can install it [here](https://brew.sh).</Tip>
      </Step>

      <Step title="Authenticate">
        ```bash theme={null}
        topk login
        ```

        <Info>
          This command prompts you to either create a new API key or set an existing one.

          You can also skip the `topk login` command and authenticate by providing your API key via the `TOPK_API_KEY` environment variable:

          ```bash theme={null}
          export TOPK_API_KEY="your-api-key"
          ```
        </Info>
      </Step>

      <Step title="Create a dataset">
        A dataset is a named container for your documents.
        To create a dataset, run the following command:

        ```bash theme={null}
        topk dataset create quickstart --region aws-us-east-1-elastica
        ```

        <Info>The `--region` flag determines where your data is stored. See [available regions](/regions).</Info>
      </Step>

      <Step title="Upload a file">
        Upload a file to your dataset:

        <Tip>
          Download a sample PDF financial report:

          ```bash theme={null}
          curl -L https://topk-docs.s3.us-east-2.amazonaws.com/bank_of_america_2024.pdf -o report.pdf
          ```
        </Tip>

        ```bash theme={null}
        topk upload ./report.pdf --dataset quickstart
        ```
      </Step>

      <Step title="Ask a question">
        ```bash theme={null}
        topk ask "What was the total net income of Bank of America in 2024?" -d quickstart
        ```

        <Info>
          **Answer:**

          * Bank of America's total net income for 2024 was \$27,132 million (approximately \$27.1 billion). <Badge color="purple">1</Badge> <Badge color="purple">2</Badge> <Badge color="purple">3</Badge> <Badge color="purple">4</Badge> <Badge color="purple">5</Badge> <Badge color="purple">6</Badge>
          * The 2024 net income represented an increase from the \$26.5 billion reported in 2023. <Badge color="purple">3</Badge> <Badge color="purple">4</Badge> <Badge color="purple">6</Badge>
          * The increase was driven by higher noninterest income, partially offset by a higher provision for credit losses and lower net interest income. <Badge color="purple">3</Badge> <Badge color="purple">6</Badge>

          **Citations:**

          <ul className="list-none pl-2 space-y-2">
            <li><Badge color="purple">1</Badge> Condensed Statement of Cash Flows showing net income of \$27,132m (2024) vs \$26,515m (2023)<br /><a href="https://topk-docs.s3.us-east-2.amazonaws.com/bank_of_america_2024.pdf#page=170" target="_blank" rel="noopener noreferrer">bank\_of\_america\_2024.pdf</a> <Badge color="gray" shape="pill">p. 170</Badge></li>
            <li><Badge color="purple">2</Badge> Consolidated Statement of Comprehensive Income: net income line item for 2024–2022<br /><a href="https://topk-docs.s3.us-east-2.amazonaws.com/bank_of_america_2024.pdf#page=92" target="_blank" rel="noopener noreferrer">bank\_of\_america\_2024.pdf</a> <Badge color="gray" shape="pill">p. 92</Badge></li>
            <li><Badge color="purple">3</Badge> Supporting figure from the filing (tabular financial excerpt)<br /><a href="https://topk-docs.s3.us-east-2.amazonaws.com/boa-ask-ref-3-figure.jpg" target="_blank" rel="noopener noreferrer">boa-ask-ref-3-figure.jpg</a></li>
            <li><Badge color="purple">4</Badge> Key performance indicators—selected annual financial data (including net income)<br /><a href="https://topk-docs.s3.us-east-2.amazonaws.com/bank_of_america_2024.pdf#page=33" target="_blank" rel="noopener noreferrer">bank\_of\_america\_2024.pdf</a> <Badge color="gray" shape="pill">pp. 33–36</Badge></li>
            <li><Badge color="purple">5</Badge> Segment results tying to total-corporation net income<br /><a href="https://topk-docs.s3.us-east-2.amazonaws.com/bank_of_america_2024.pdf#page=166" target="_blank" rel="noopener noreferrer">bank\_of\_america\_2024.pdf</a> <Badge color="gray" shape="pill">pp. 166–168</Badge></li>
            <li><Badge color="purple">6</Badge> Executive summary—summary income statement and balance sheet excerpts<br /><a href="https://topk-docs.s3.us-east-2.amazonaws.com/bank_of_america_2024.pdf#page=29" target="_blank" rel="noopener noreferrer">bank\_of\_america\_2024.pdf</a> <Badge color="gray" shape="pill">pp. 29–30</Badge></li>
          </ul>
        </Info>

        <Accordion title="Full JSON output">
          ```json theme={null}
          {
            "facts": [
              {
                "fact": "Bank of America's total net income for the fiscal year 2024 was $27,132 million.",
                "ref_ids": ["1", "2", "3", "4", "5", "6"]
              },
              {
                "fact": "The 2024 net income of $27.1 billion represented an increase from the $26.5 billion reported in 2023.",
                "ref_ids": ["3", "4", "6"]
              },
              {
                "fact": "The increase was driven by higher noninterest income, partially offset by a higher provision for credit losses and lower net interest income.",
                "ref_ids": ["3", "6"]
              }
            ],
            "refs": {
              "1": {
                "doc_id": "bank-of-america-annual-report-2024",
                "doc_type": "application/pdf",
                "dataset": "quickstart",
                "content_id": "doc#bank-of-america-annual-report-2024#chunk#130",
                "doc_name": "report.pdf",
                "content": {
                  "text": "## Condensed Statement of Cash Flows\n[row_1]; []=Net income; [2024]=27,132; [2023]=26,515; [2022]=27,528\n...",
                  "doc_pages": [170]
                }
              },
              "2": {
                "doc_id": "bank-of-america-annual-report-2024",
                "doc_type": "application/pdf",
                "dataset": "quickstart",
                "content_id": "doc#bank-of-america-annual-report-2024#chunk#428",
                "doc_name": "report.pdf",
                "content": {
                  "text": "## Consolidated Statement of Comprehensive Income\n[row_0]; [Dollars in millions]=Net income; [2024]=27,132; [2023]=26,515; [2022]=27,528\n...",
                  "doc_pages": [92]
                }
              },
              "3": {
                "doc_id": "bank-of-america-annual-report-2024",
                "doc_type": "application/pdf",
                "dataset": "quickstart",
                "content_id": "doc#bank-of-america-annual-report-2024#image#92",
                "doc_name": "report.pdf",
                "content": {
                  "mime_type": "image/jpeg",
                  "data": "<base64 encoded image>"
                }
              },
              "4": {
                "doc_id": "bank-of-america-annual-report-2024",
                "doc_type": "application/pdf",
                "dataset": "quickstart",
                "content_id": "doc#bank-of-america-annual-report-2024#chunk#129",
                "doc_name": "report.pdf",
                "content": {
                  "text": "## Key Performance Indicators\n[row_7]=Income statement; []=Net income; [2024]=27,132; [2023]=26,515\n...",
                  "doc_pages": [33, 34, 35, 36]
                }
              },
              "5": {
                "doc_id": "bank-of-america-annual-report-2024",
                "doc_type": "application/pdf",
                "dataset": "quickstart",
                "content_id": "doc#bank-of-america-annual-report-2024#chunk#854",
                "doc_name": "report.pdf",
                "content": {
                  "text": "## Results of Business Segments\n[row_9]; [Item]=Net income; [Total Corporation (2) 2024]=27,132; [Total Corporation (2) 2023]=26,515\n...",
                  "doc_pages": [166, 167, 168]
                }
              },
              "6": {
                "doc_id": "bank-of-america-annual-report-2024",
                "doc_type": "application/pdf",
                "dataset": "quickstart",
                "content_id": "doc#bank-of-america-annual-report-2024#chunk#131",
                "doc_name": "report.pdf",
                "content": {
                  "text": "## Executive Summary > Financial Highlights\n[row_7]=Net income; [2024]=27,132; [2023]=26,515\n...",
                  "doc_pages": [29, 30]
                }
              }
            },
            "confidence": 100.0
          }
          ```
        </Accordion>

        <Note>
          To learn more about how to use TopK CLI, see the [CLI documentation](/cli).
        </Note>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Python SDK" icon="https://mintcdn.com/topk/8NBkS0nek3e9o6Vi/icons/python.svg?fit=max&auto=format&n=8NBkS0nek3e9o6Vi&q=85&s=97cbee7891538170fd752e1afbc98095" width="128" height="128" data-path="icons/python.svg">
    <Steps>
      <Step title="Install Python SDK">
        <CodeGroup>
          ```bash pip theme={null}
          pip install topk-sdk
          ```

          ```bash uv theme={null}
          uv add topk-sdk
          ```
        </CodeGroup>
      </Step>

      <Step title="Initialize the client">
        Setup the TopK client with your API key and region.

        <CodeGroup>
          ```python Sync theme={null}
          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"),
          )
          ```

          ```python Async theme={null}
          import os
          from topk_sdk import AsyncClient

          client = AsyncClient(
              api_key=os.environ["TOPK_API_KEY"],
              region=os.environ.get("TOPK_REGION", "aws-us-east-1-elastica"),
          )
          ```
        </CodeGroup>

        <Info>See [available regions](/regions) for a full list of supported regions.</Info>
      </Step>

      <Step title="Create a dataset">
        <CodeGroup>
          ```python Sync theme={null}
          client.datasets().create("quickstart")
          ```

          ```python Async theme={null}
          await client.datasets().create("quickstart")
          ```
        </CodeGroup>
      </Step>

      <Step title="Upload a file">
        Upload a file to your dataset by providing the document ID, the path to the file, and optional metadata:

        <Tip>
          Download a sample PDF financial report:

          ```bash theme={null}
          curl -L https://topk-docs.s3.us-east-2.amazonaws.com/bank_of_america_2024.pdf -o report.pdf
          ```
        </Tip>

        <CodeGroup>
          ```python Sync theme={null}
          from pathlib import Path

          handle = client.dataset("quickstart").upsert_file(
              "bank-of-america-annual-report-2024",  # document ID
              Path("./report.pdf"),                  # path to file
              {
                  "ticker": "BAC",
                  "doc_type": "annual_report",
                  "fiscal_year": 2024,
              },
          )
          ```

          ```python Async theme={null}
          from pathlib import Path

          handle = await client.dataset("quickstart").upsert_file(
              "bank-of-america-annual-report-2024",  # document ID
              Path("./report.pdf"),                  # path to file
              {
                  "ticker": "BAC",
                  "doc_type": "annual_report",
                  "fiscal_year": 2024,
              },
          )
          ```
        </CodeGroup>

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

        <CodeGroup>
          ```python Sync theme={null}
          client.dataset("quickstart").wait_for_handle(handle)
          ```

          ```python Async theme={null}
          await client.dataset("quickstart").wait_for_handle(handle)
          ```
        </CodeGroup>
      </Step>

      <Step title="Ask a question">
        <CodeGroup>
          ```python Sync theme={null}
          for message in client.ask("What was the total net income of Bank of America in 2024?", ["quickstart"]):
              print(message)
          ```

          ```python Async theme={null}
          async for message in client.ask("What was the total net income of Bank of America in 2024?", ["quickstart"]):
              print(message)
          ```
        </CodeGroup>

        <Accordion title="Full JSON output">
          ```json theme={null}
          {
            "facts": [
              {
                "fact": "Bank of America's total net income for the fiscal year 2024 was $27,132 million.",
                "ref_ids": ["1", "2", "3", "4", "5", "6"]
              },
              {
                "fact": "The 2024 net income of $27.1 billion represented an increase from the $26.5 billion reported in 2023.",
                "ref_ids": ["3", "4", "6"]
              },
              {
                "fact": "The increase in 2024 net income was driven by higher noninterest income, although this was partially offset by a higher provision for credit losses and lower net interest income.",
                "ref_ids": ["3", "6"]
              }
            ],
            "refs": {
              "1": {
                "doc_id": "bank-of-america-annual-report-2024",
                "doc_type": "application/pdf",
                "dataset": "quickstart",
                "content_id": "doc#bank-of-america-annual-report-2024#chunk#130",
                "doc_name": "report.pdf",
                "content": {
                  "data": {
                    "Chunk": {
                      "text": "## Condensed Statement of Cash Flows\n[row_1]; []=Net income; [2024]=27,132; [2023]=26,515; [2022]=27,528\n...",
                      "doc_pages": [170]
                    }
                  }
                }
              },
              "2": {
                "doc_id": "bank-of-america-annual-report-2024",
                "doc_type": "application/pdf",
                "dataset": "quickstart",
                "content_id": "doc#bank-of-america-annual-report-2024#chunk#428",
                "doc_name": "report.pdf",
                "content": {
                  "data": {
                    "Chunk": {
                      "text": "## Consolidated Statement of Comprehensive Income\n[row_0]; [Dollars in millions]=Net income; [2024]=27,132; [2023]=26,515; [2022]=27,528\n...",
                      "doc_pages": [92]
                    }
                  }
                }
              },
              "3": {
                "doc_id": "bank-of-america-annual-report-2024",
                "doc_type": "application/pdf",
                "dataset": "quickstart",
                "content_id": "doc#bank-of-america-annual-report-2024#image#92",
                "doc_name": "report.pdf",
                "content": {
                  "data": {
                    "Image": {
                      "mime_type": "image/jpeg",
                      "data": "<base64 encoded image>"
                    }
                  }
                }
              },
              "4": {
                "doc_id": "bank-of-america-annual-report-2024",
                "doc_type": "application/pdf",
                "dataset": "quickstart",
                "content_id": "doc#bank-of-america-annual-report-2024#chunk#129",
                "doc_name": "report.pdf",
                "content": {
                  "data": {
                    "Chunk": {
                      "text": "## Key Performance Indicators\n[row_7]=Income statement; []=Net income; [2024]=27,132; [2023]=26,515\n...",
                      "doc_pages": [33, 34, 35, 36]
                    }
                  }
                }
              },
              "5": {
                "doc_id": "bank-of-america-annual-report-2024",
                "doc_type": "application/pdf",
                "dataset": "quickstart",
                "content_id": "doc#bank-of-america-annual-report-2024#chunk#854",
                "doc_name": "report.pdf",
                "content": {
                  "data": {
                    "Chunk": {
                      "text": "## Results of Business Segments\n[row_9]; [Item]=Net income; [Total Corporation (2) 2024]=27,132; [Total Corporation (2) 2023]=26,515\n...",
                      "doc_pages": [166, 167, 168]
                    }
                  }
                }
              },
              "6": {
                "doc_id": "bank-of-america-annual-report-2024",
                "doc_type": "application/pdf",
                "dataset": "quickstart",
                "content_id": "doc#bank-of-america-annual-report-2024#chunk#131",
                "doc_name": "report.pdf",
                "content": {
                  "data": {
                    "Chunk": {
                      "text": "## Executive Summary > Financial Highlights\n[row_7]=Net income; [2024]=27,132; [2023]=26,515\n...",
                      "doc_pages": [29, 30]
                    }
                  }
                }
              }
            },
            "confidence": 100.0
          }
          ```
        </Accordion>

        <Note>
          To learn more about how to use the Python SDK, see the [Python SDK documentation](/sdk/topk-py).
        </Note>
      </Step>
    </Steps>
  </Tab>

  <Tab title="JavaScript SDK" icon="https://mintcdn.com/topk/8NBkS0nek3e9o6Vi/icons/js.svg?fit=max&auto=format&n=8NBkS0nek3e9o6Vi&q=85&s=7642cf18b45f52a70f141214b3d0eca1" width="24" height="24" data-path="icons/js.svg">
    <Steps>
      <Step title="Install JavaScript SDK">
        <CodeGroup>
          ```bash npm theme={null}
          npm install topk-js
          ```

          ```bash yarn theme={null}
          yarn add topk-js
          ```

          ```bash pnpm theme={null}
          pnpm add topk-js
          ```
        </CodeGroup>
      </Step>

      <Step title="Initialize the client">
        ```typescript theme={null}
        import { Client } from "topk-js";

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

        <Info>See [available regions](/regions) for a full list of supported regions.</Info>
      </Step>

      <Step title="Create a dataset">
        ```typescript theme={null}
        await client.datasets().create("quickstart");
        ```
      </Step>

      <Step title="Upload a file">
        <Tip>
          Download a sample PDF financial report:

          ```bash theme={null}
          curl -L https://topk-docs.s3.us-east-2.amazonaws.com/bank_of_america_2024.pdf -o report.pdf
          ```
        </Tip>

        ```typescript theme={null}
        const handle = await client.dataset("quickstart").upsertFile(
          "bank-of-america-annual-report-2024", // document ID
          { path: "./report.pdf" },             // path to file
          {
            ticker: "BAC",
            doc_type: "annual_report",
            fiscal_year: 2024,
          },
        );
        ```

        Wait for the file to be processed:

        ```typescript theme={null}
        await client.dataset("quickstart").waitForHandle(handle);
        ```
      </Step>

      <Step title="Ask a question">
        ```typescript theme={null}
        for await (const message of client.ask("What was the total net income of Bank of America in 2024?", ["quickstart"])) {
          console.log(message);
        }
        ```

        <Accordion title="Full JSON output">
          ```json theme={null}
          {
            "facts": [
              {
                "fact": "Bank of America's total net income for the fiscal year 2024 was $27,132 million.",
                "refIds": ["1", "2", "3", "4", "5", "6"]
              },
              {
                "fact": "The 2024 net income of $27.1 billion represented an increase from the $26.5 billion reported in 2023.",
                "refIds": ["3", "4", "6"]
              },
              {
                "fact": "The increase in 2024 net income was driven by higher noninterest income, although this was partially offset by a higher provision for credit losses and lower net interest income.",
                "refIds": ["3", "6"]
              }
            ],
            "refs": {
              "1": {
                "docId": "bank-of-america-annual-report-2024",
                "docType": "application/pdf",
                "dataset": "quickstart",
                "contentId": "doc#bank-of-america-annual-report-2024#chunk#130",
                "docName": "report.pdf",
                "content": {
                  "type": "chunk",
                  "data": {
                    "text": "## Condensed Statement of Cash Flows\n[row_1]; []=Net income; [2024]=27,132; [2023]=26,515; [2022]=27,528\n...",
                    "docPages": [170]
                  }
                }
              },
              "2": {
                "docId": "bank-of-america-annual-report-2024",
                "docType": "application/pdf",
                "dataset": "quickstart",
                "contentId": "doc#bank-of-america-annual-report-2024#chunk#428",
                "docName": "report.pdf",
                "content": {
                  "type": "chunk",
                  "data": {
                    "text": "## Consolidated Statement of Comprehensive Income\n[row_0]; [Dollars in millions]=Net income; [2024]=27,132; [2023]=26,515; [2022]=27,528\n...",
                    "docPages": [92]
                  }
                }
              },
              "3": {
                "docId": "bank-of-america-annual-report-2024",
                "docType": "application/pdf",
                "dataset": "quickstart",
                "contentId": "doc#bank-of-america-annual-report-2024#image#92",
                "docName": "report.pdf",
                "content": {
                  "type": "image",
                  "data": {
                    "mimeType": "image/jpeg",
                    "data": "<base64 encoded image>"
                  }
                }
              },
              "4": {
                "docId": "bank-of-america-annual-report-2024",
                "docType": "application/pdf",
                "dataset": "quickstart",
                "contentId": "doc#bank-of-america-annual-report-2024#chunk#129",
                "docName": "report.pdf",
                "content": {
                  "type": "chunk",
                  "data": {
                    "text": "## Key Performance Indicators\n[row_7]=Income statement; []=Net income; [2024]=27,132; [2023]=26,515\n...",
                    "docPages": [33, 34, 35, 36]
                  }
                }
              },
              "5": {
                "docId": "bank-of-america-annual-report-2024",
                "docType": "application/pdf",
                "dataset": "quickstart",
                "contentId": "doc#bank-of-america-annual-report-2024#chunk#854",
                "docName": "report.pdf",
                "content": {
                  "type": "chunk",
                  "data": {
                    "text": "## Results of Business Segments\n[row_9]; [Item]=Net income; [Total Corporation (2) 2024]=27,132; [Total Corporation (2) 2023]=26,515\n...",
                    "docPages": [166, 167, 168]
                  }
                }
              },
              "6": {
                "docId": "bank-of-america-annual-report-2024",
                "docType": "application/pdf",
                "dataset": "quickstart",
                "contentId": "doc#bank-of-america-annual-report-2024#chunk#131",
                "docName": "report.pdf",
                "content": {
                  "type": "chunk",
                  "data": {
                    "text": "## Executive Summary > Financial Highlights\n[row_7]=Net income; [2024]=27,132; [2023]=26,515\n...",
                    "docPages": [29, 30]
                  }
                }
              }
            },
            "confidence": 100.0
          }
          ```
        </Accordion>

        <Note>
          To learn more about how to use the JavaScript SDK, see the [JavaScript SDK documentation](/sdk/topk-js).
        </Note>
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Integrations

<CardGroup cols={2}>
  <Card title="Python SDK" icon="https://mintcdn.com/topk/8NBkS0nek3e9o6Vi/icons/python.svg?fit=max&auto=format&n=8NBkS0nek3e9o6Vi&q=85&s=97cbee7891538170fd752e1afbc98095" href="/sdk/topk-py/overview" width="128" height="128" data-path="icons/python.svg">
    Full Python SDK reference.
  </Card>

  <Card title="JavaScript SDK" icon="https://mintcdn.com/topk/8NBkS0nek3e9o6Vi/icons/js.svg?fit=max&auto=format&n=8NBkS0nek3e9o6Vi&q=85&s=7642cf18b45f52a70f141214b3d0eca1" href="/sdk/topk-js/overview" width="24" height="24" data-path="icons/js.svg">
    Full TypeScript/JavaScript SDK reference.
  </Card>

  <Card title="CLI" icon="terminal" href="/cli">
    Upload files, search, and ask questions directly from the terminal.
  </Card>

  <Card title="MCP Server" icon="network" href="/mcp-server">
    Connect TopK to any MCP-compatible AI agent via the Model Context Protocol.
  </Card>
</CardGroup>

## Security & Compliance

TopK is **SOC 2 Type I** certified. Visit the [trust center](https://trust.topk.io) for full details.

<CardGroup cols={1}>
  <Card title="Data encryption" icon="lock" horizontal>
    All data is encrypted in transit and at rest.
  </Card>

  <Card title="Access control" icon="shield-check" horizontal>
    Role-based access control with full auditability.
  </Card>

  <Card title="Private Deployment" icon="server" horizontal>
    Deploy inside your own VPC for complete isolation and data residency. [Contact us](https://topk.io/contact) for more details.
  </Card>
</CardGroup>

## Learn More

<CardGroup cols={2}>
  <Card title="Architecture" icon="server" href="/architecture">
    Learn about TopK's architecture and how it works.
  </Card>

  <Card title="Concepts" icon="info" href="/concepts">
    Discover core concepts and how they work together.
  </Card>
</CardGroup>