Integration

While you can use the Hyperspell API directly to query data, the most common way to query data is using the Hyperspell SDKs, which are available Python and TypeScript.

​

Installation

pip install hyperspell
# Or using Poetry
poetry add hyperspell
# Or using uv
uv add hyperspell

To initialize the client, you need to generate an app token in your dashboard.

from hyperspell import Hyperspell

client = Hyperspell(api_key="YOUR_APP_TOKEN")

You can also set the HYPERSPELL_API_KEY environment variable and omit the api_key parameter when initializing the client. An app token allows you to insert and query data for any user of your app. Please refer to the Generating Tokens section for more information on how to generate user tokens that are specific to a single user instead.

​

Usage

Before you can query data, you need to add a document to a collection. In this example, we’ll add a URL. Every document is associated with a collection, however, you don’t need to create the collection beforehand. If the collection doesn’t exist, it will be created automatically.

document_status = client.documents.add_url(
    url="https://www.hyperspell.com",
    collection="my-collection"
)
print(document_status.id)

The id returned will be the ID of the document. You can use this ID to query the document later. Some types of documents may take several seconds to process, so you may need to wait for the document to be processed before you can query it.

Once you have added a document, you can query it using the query method.