Meilisearch Getting Started: Setup and First Request (2026)

Getting started overview

Integrating Meilisearch involves setting up an instance, obtaining API keys, and then programmatically interacting with the search engine to index data and perform queries. Meilisearch offers two primary deployment methods: Meilisearch Cloud, a managed service, and a self-hosted option that provides direct control over the server environment. This guide focuses on the streamlined process for new users, detailing how to get an instance running, secure access credentials, and execute an initial search request to verify your setup. Regardless of the deployment choice, the core API interactions remain consistent, allowing developers to choose the environment that best suits their operational needs and existing infrastructure. For a comprehensive understanding of all configuration options, consult the official Meilisearch installation guide.

The following table provides a quick reference for the essential steps to get started with Meilisearch:

Create an account and get keys

To begin using Meilisearch, you need an operational instance and corresponding API keys for authentication. Your approach will vary based on whether you opt for Meilisearch Cloud or a self-hosted setup.

Meilisearch Cloud

1. Sign Up: Navigate to the Meilisearch Cloud website and sign up for a new account. A free tier is available, supporting up to 250,000 documents and 100,000 search requests per month.
2. Create Project: Follow the prompts to create your first project. This will provision a dedicated Meilisearch instance for your use.
3. Locate API Keys: Once your project is active, access your project dashboard. Here, you will find your API keys, typically listed under a "Settings" or "API Keys" section. Meilisearch Cloud provides different types of keys, such as public (search-only) and private (admin access), along with your master key. The Meilisearch documentation on API keys provides detailed explanations of each key type and their permissions.

Self-Hosted Meilisearch

For self-hosting, you install Meilisearch directly on your server or local machine. This requires command-line interaction and environment configuration.

1. Installation: Choose your preferred installation method, such as Docker, Homebrew, or direct binary download. For example, using Docker:

   docker pull getmeili/meilisearch:latest
   docker run -it --rm -p 7700:7700 -h meilisearch getmeili/meilisearch:latest meilisearch --master-key your_master_key

   Replace your_master_key with a strong, unique key. This key is crucial for securing your instance and performing administrative tasks. The Meilisearch installation guide offers detailed instructions for various operating systems and deployment strategies.

2. Access Master Key: In a self-hosted setup, the master key is either passed as a command-line argument during startup or configured via environment variables. This key acts as the primary access credential for your Meilisearch instance.
3. API Keys (Optional): While the master key grants full access, you can also generate more granular API keys for specific permissions (e.g., read-only access for your frontend application) using the Meilisearch API itself. This practice aligns with the principle of least privilege, enhancing security. The Meilisearch API Keys documentation details how to manage these keys programmatically.

It is best practice to store your master key and any private API keys securely, for example, using environment variables or a secrets management service, rather than hardcoding them directly into your application code. For guidance on secure credential management, refer to general best practices for API security, such as those outlined by resource like the Google Cloud API Key best practices.

Your first request

After setting up your Meilisearch instance and obtaining your API key, the next step is to interact with it. This involves initializing a client, indexing some data, and then performing a search query. This example uses the JavaScript SDK, but similar logic applies to other Meilisearch SDKs.

1. Install an SDK

Choose the SDK corresponding to your application's programming language. For JavaScript:

npm install meilisearch

2. Initialize the client

Create an instance of the Meilisearch client, providing your host URL and API key. For self-hosted, the default host is http://localhost:7700. For Meilisearch Cloud, use the host URL provided in your project dashboard.

import { MeiliSearch } from 'meilisearch'

const client = new MeiliSearch({
  host: 'YOUR_MEILISEARCH_HOST',
  apiKey: 'YOUR_MASTER_KEY_OR_PRIVATE_API_KEY',
})

Replace YOUR_MEILISEARCH_HOST and YOUR_MASTER_KEY_OR_PRIVATE_API_KEY with your actual Meilisearch instance details.

3. Create an index and add documents

Meilisearch organizes data into indexes. Create an index and add some sample documents. Each document must have a unique id field.

async function addDocuments() {
  const index = client.index('movies')

  const documents = [
    { id: 1, title: 'The Shawshank Redemption', genres: ['Drama'] },
    { id: 2, title: 'The Dark Knight', genres: ['Action', 'Crime', 'Drama'] },
    { id: 3, title: 'Pulp Fiction', genres: ['Crime', 'Drama'] },
    { id: 4, title: 'The Lord of the Rings: The Return of the King', genres: ['Action', 'Adventure', 'Drama'] },
    { id: 5, title: 'Forrest Gump', genres: ['Comedy', 'Drama', 'Romance'] }
  ]

  const response = await index.addDocuments(documents)
  console.log('Documents added:', response)
}

addDocuments()

The addDocuments method returns an update ID. You can use this ID to check the status of the indexing operation using index.getUpdateStatus(updateId).

4. Perform a search

Once documents are indexed, you can perform a search query. Use the search method on your index.

async function searchDocuments() {
  const index = client.index('movies')

  const searchResult = await index.search('dark knight')
  console.log('Search Result:', searchResult.hits)

  const filteredSearchResult = await index.search('drama', {
    filter: ['genres = Drama']
  })
  console.log('Filtered Search Result (Drama):', filteredSearchResult.hits)
}

searchDocuments()

This code performs a basic search for "dark knight" and a filtered search for movies in the "Drama" genre. The hits array in the response contains the matching documents.

Common next steps

After successfully performing your first search request, consider these common next steps to further integrate and optimize Meilisearch:

• Configure Index Settings: Meilisearch provides extensive index settings to fine-tune search relevance, such as defining searchable attributes, sortable attributes, stop words, and synonyms. Understanding these settings is crucial for optimizing your search experience. Consult the Meilisearch relevancy documentation to customize your search behavior.
• Implement Advanced Search Features: Explore features like filtering, faceting, and sorting to build more dynamic and user-friendly search interfaces. These capabilities allow users to refine their search results based on various criteria. The Meilisearch filtering and faceting guide provides detailed examples.
• Manage Data Updates: Develop a strategy for incrementally updating, adding, or deleting documents in your Meilisearch indexes to keep your search results current. This often involves integrating Meilisearch into your data pipeline or content management system.
• Secure Your Instance: Review and implement best practices for securing your Meilisearch instance, especially if it's publicly accessible. This includes managing API keys, enabling HTTPS, and configuring network access controls.
• Monitor Performance: Set up monitoring for your Meilisearch instance to track performance, resource usage, and error rates. This helps ensure search remains fast and reliable as your data and query volumes grow.
• Frontend Integration: Integrate Meilisearch with your frontend application using a dedicated UI library or by directly consuming the search API. Libraries like InstantSearch.js (compatible with Meilisearch via adapters) can accelerate development of sophisticated search UIs.

Troubleshooting the first call

Encountering issues during your initial Meilisearch setup is common. Here are some frequent problems and their solutions:

• Connection Refused (Self-Hosted):

  • Cause: Meilisearch instance is not running or is not accessible on the specified host and port.
  • Solution: Ensure Meilisearch is running. If using Docker, verify the container is up and port 7700 is mapped correctly (-p 7700:7700). Check firewall rules to ensure incoming connections to port 7700 are allowed. The Meilisearch documentation on running Meilisearch has startup commands.

• Invalid API Key / Unauthorized Access:

  • Cause: The API key provided in your client initialization is incorrect, expired, or lacks the necessary permissions for the operation.
  • Solution: Double-check your API key against the one in your Meilisearch Cloud dashboard or the master key used to start your self-hosted instance. Ensure you are using a key with appropriate permissions for the operation (e.g., a private key for adding documents, a public key for searching).

• Index Not Found:

  • Cause: You are trying to perform an operation on an index that has not yet been created or for which indexing is still pending.
  • Solution: Verify that your addDocuments call successfully completed and the documents were indexed. Meilisearch creates an index automatically when you add documents to it if it doesn't exist, but there might be a delay for indexing large datasets.

• CORS Issues (Frontend Applications):

  • Cause: Your frontend application (browser) is trying to access a Meilisearch instance on a different origin without proper Cross-Origin Resource Sharing (CORS) configuration.
  • Solution: Configure your Meilisearch instance to allow requests from your frontend's origin. For self-hosted instances, use the --http-addr and --cors-allow-origin flags during startup. Meilisearch Cloud typically handles common CORS configurations automatically. The Meilisearch configuration options explain these flags.

• Empty Search Results:

  • Cause: No documents match your search query, or the indexing process for your documents has not completed.
  • Solution: Confirm that documents were successfully added to the index and that your search query matches content within those documents. Check the update status of your indexing tasks to ensure all documents have been processed.