Typesense Getting Started: Quickstart Guide & First Request (2026)

Getting started overview

Typesense is a fast, open-source search engine designed for building instant search experiences. This guide focuses on the initial steps to get a Typesense instance running and execute a first API request. Users can choose between Typesense Cloud, a managed service, or a self-hosted deployment. Typesense Cloud simplifies infrastructure management, while self-hosting offers greater control over the deployment environment.

The core process involves:

1. Setting up an instance: Either creating a Typesense Cloud account and launching a cluster, or deploying the Typesense server on a self-managed environment.
2. Obtaining API keys: Generating an API key for secure authentication with the Typesense cluster.
3. Making a first request: Interacting with the Typesense API to create a collection, index a document, and perform a search query.

This guide will primarily use Typesense Cloud for the setup steps due to its streamlined onboarding. The API interaction steps are largely consistent across both deployment methods.

Create an account and get keys

To begin with Typesense Cloud, you need to create an account and provision a search cluster. If you opt for self-hosting, refer to the Typesense self-hosting documentation for installation instructions on your preferred platform (e.g., Docker, Linux, macOS).

Typesense Cloud setup

1. Sign up for Typesense Cloud: Navigate to the Typesense Cloud signup page. You can register using an email address or a Google account. A free developer plan is available, offering 1GB RAM and 1GB disk space without requiring a credit card.
2. Create a new cluster: After signing in, you will be prompted to create a new cluster. Provide a cluster name, select a region, and choose your desired plan. For initial testing, the free Developer plan is sufficient.
3. Wait for cluster provisioning: Typesense Cloud will provision your cluster, which usually takes a few minutes. Once complete, you will see your cluster details on the dashboard.
4. Obtain API Key and Host: From your cluster dashboard, locate the API Keys section. You will find several keys, including an Admin API Key and a Search-Only API Key. For initial data indexing and administrative tasks, the Admin API Key is required. Also note your Host (e.g., xxx.typesense.net) and Port (typically 443 for HTTPS) from the cluster details.

Quick Reference: Getting Started Steps

Your first request

This section demonstrates how to create a collection, index a document, and perform a search query using the Typesense API. We'll use Python for the examples, but the principles apply across all Typesense client libraries (JavaScript, PHP, Ruby, Go, Dart, Java).

1. Install the Typesense client library

First, install the Python client library:

pip install typesense

2. Initialize the client

Configure the Typesense client with your cluster's host, port, protocol, and API key:

import typesense

client = typesense.Client({
  'nodes': [{
    'host': 'YOUR_TYPESENSE_HOST', # e.g., xxx.typesense.net
    'port': '443',
    'protocol': 'https'
  }],
  'api_key': 'YOUR_ADMIN_API_KEY', # Use Admin API Key for indexing
  'connection_timeout_seconds': 2
})

Replace YOUR_TYPESENSE_HOST and YOUR_ADMIN_API_KEY with the values obtained from your Typesense Cloud dashboard or your self-hosted setup.

3. Define a collection schema

Before indexing data, you must define a collection schema. This schema specifies the fields in your documents and their data types, similar to defining a table in a relational database. Typesense supports various field types like string, int32, float, bool, and string[].

schema = {
  'name': 'books',
  'fields': [
    {'name': 'title', 'type': 'string'},
    {'name': 'author', 'type': 'string'},
    {'name': 'publication_year', 'type': 'int32'},
    {'name': 'isbn', 'type': 'string', 'facet': True}
  ],
  'default_sorting_field': 'publication_year'
}

try:
  client.collections.create(schema)
  print("Collection 'books' created successfully")
except typesense.exceptions.ObjectAlreadyExists:
  print("Collection 'books' already exists")

4. Index a document

Once the collection is created, you can add documents to it. Each document must conform to the defined schema.

document = {
  'id': '124',
  'title': 'The Lord of the Rings',
  'author': 'J.R.R. Tolkien',
  'publication_year': 1954,
  'isbn': '978-0618053267'
}

client.collections['books'].documents.create(document)
print("Document indexed successfully")

5. Search for documents

Now, perform a search query against your indexed data. Typesense provides powerful search capabilities, including typo tolerance, faceting, and sorting.

search_parameters = {
  'q': 'lord rings',
  'query_by': 'title,author',
  'sort_by': 'publication_year:desc'
}

search_results = client.collections['books'].documents.search(search_parameters)
print("Search Results:")
for hit in search_results['hits']:
  print(hit['document'])

This query searches for 'lord rings' across the 'title' and 'author' fields and sorts the results by 'publication_year' in descending order.

Common next steps

After successfully performing your first search, consider these common next steps to further integrate Typesense into your application:

• Explore advanced search features: Typesense supports features like grouping results, faceting, federated search, and synonyms. Understanding these can enhance the search experience.
• Integrate with your frontend: For instant search experiences, integrate Typesense with your frontend framework. Typesense provides libraries and guides for popular frameworks like React, Vue, and vanilla JavaScript.
• Implement data synchronization: For dynamic data, set up a mechanism to synchronize your application's data with Typesense. This can involve using webhooks, message queues, or scheduled tasks to push updates, additions, and deletions to your Typesense cluster. For example, a database trigger could send updates to a message queue, which then processes and sends the data to Typesense. This is a common pattern for maintaining data consistency across systems, as detailed in general data synchronization strategies.
• Monitor and scale: Monitor your Typesense cluster's performance and resource usage. Typesense Cloud provides monitoring tools, and for self-hosted deployments, integrate with your existing monitoring solutions. Plan for scaling your cluster as your data volume and query load increase.
• Review security best practices: Ensure you are using appropriate API keys (e.g., Search-Only API Key for frontend searches) and securing your API keys.

Troubleshooting the first call

When encountering issues with your first Typesense API call, consider the following common problems and solutions:

• Incorrect API Key or Host: Double-check that the api_key and host values in your client initialization match those from your Typesense Cloud dashboard or self-hosted configuration. Ensure you are using the Admin API Key for creating collections and indexing documents, as the Search-Only API Key does not have these permissions. Incorrect credentials are a frequent cause of Unauthorized or Forbidden errors.
• Network Connectivity: Verify that your application can reach the Typesense cluster. If using Typesense Cloud, ensure there are no firewall rules blocking outbound connections to *.typesense.net on port 443. For self-hosted instances, confirm the Typesense server is running and accessible on the specified port.
• Schema Mismatch: If you receive errors when indexing documents, ensure that the fields and their data types in your document exactly match the collection schema you defined. For instance, attempting to index a string into an int32 field will result in an error. The Typesense API documentation provides detailed information on schema requirements.
• Collection Already Exists: If you try to create a collection with a name that already exists, Typesense will return an ObjectAlreadyExists exception. Wrap your client.collections.create(schema) call in a try-except block to handle this gracefully, as shown in the example.
• Client Library Version: Ensure you are using a compatible version of the Typesense client library. Refer to the official Typesense client library documentation for version compatibility information.
• Check Server Logs: For self-hosted deployments, review the Typesense server logs for detailed error messages. These logs can provide specific insights into why a request failed.