Meilisearch Integration

Want to build powerful search into your workflows? Connect Meilisearch to SmythOS and let your agents manage indexes, add documents, and run complex search queries automatically.

TL;DR

Link your Meilisearch instance to SmythOS using your Host URL and a Master Key. Then, use our Meilisearch components to enable your agents to automate indexing, document management, and full-text search operations.

List of Meilisearch Components

Quickly compare Meilisearch components by what they do and their key I/O. Click any component name to jump directly to its detailed guide.

Component	Action	What it Does	Inputs	Key Outputs	Use Case
Full Text Search	Search	Searches for documents within a specified index.	required url, index_uid, query	results	Power a search bar in your application.
Create an Index	Setup	Creates a new, empty index with a primary key.	required url, uid, primaryKey	taskUid	Set up a new data collection for searching.
Add a Single Document	Write	Adds or updates one document in an index.	required url, index_uid optional body	taskUid	Index a new user profile as it's created.
Add Documents	Write	Adds or updates a batch of documents in an index.	required url, uid optional body	taskUid	Perform a bulk import of product data.
Update a Document	Write	Adds or updates documents in an index. (Similar to Add Documents).	required url, index_uid optional body	taskUid	Update product inventory levels in bulk.
Delete a Document	Write	Deletes a single document from an index.	required url, index_uid, document_id	taskUid	Remove a user's data upon account deletion.
Update Synonyms	Setup	Updates the list of synonyms for an index to improve search relevance.	required url, index_uid optional body	taskUid	Make "t-shirt" and "tee" return the same results.

INFO

Why Integrate Meilisearch with Your Agent?

Meilisearch provides an incredibly fast and relevant search experience. By integrating it with SmythOS, you can automate the entire lifecycle of your search data.

• Automated Indexing: As new data is created in your applications (e.g., new products, users, or posts), agents can automatically add it to your Meilisearch indexes, ensuring your search results are always fresh.
• Dynamic Content Management: Agents can update or delete documents from your indexes based on events from other systems, keeping your search data perfectly in sync with your source of truth.
• Intelligent Search Workflows: Use the Full Text Search component to find information and use it in downstream steps. For example, find a user's profile ID to then fetch their full details from a database.
• Streamline Maintenance: Automate tasks like updating synonyms to continuously improve the relevance and quality of your search results without manual intervention.

Prerequisites

Before you begin, please ensure you have the following:

• An active SmythOS account. (Sign up here).
• A running Meilisearch instance, either self-hosted or on Meilisearch Cloud.
• The Host URL of your Meilisearch instance (e.g., https://my-instance.meilisearch.com).
• Your Meilisearch Master Key.

Getting Started With Meilisearch

The connection between SmythOS and Meilisearch is configured using your instance's URL and a secure Master Key.

Step 1: Locate Your Meilisearch Credentials

1. Host URL: This is the main URL you use to access your Meilisearch instance.
2. Master Key: In your Meilisearch instance, navigate to Settings -> API Keys. Your Master Key is displayed there. It has full permissions to perform any action.

Step 2: Store Your Master Key in SmythOS Vault

Your Master Key is highly sensitive. Use the SmythOS Vault to store it securely.

1. In your SmythOS dashboard, navigate to the Vault.
2. Create a new secret and paste your Meilisearch Master Key as the value. Give it a memorable name, like meilisearch_master_key.
3. For more details, see the Vault Documentation.

Step 3: Configure a Meilisearch Component

1. In your SmythOS agent graph, drag and drop any Meilisearch component.
2. Click the component to open its Settings panel.
3. In the Master Key field, select the secret you saved in the Vault (e.g., meilisearch_master_key).
4. In the component's Inputs, provide the url of your Meilisearch instance.
5. Your connection is now configured for that component.

Heads-up

You must add the url and Master Key to each Meilisearch component you use. This provides the flexibility to connect to different Meilisearch instances within the same agent.

Which Meilisearch Component Should I Use?

If you need to…	Target	Use this Component	Why this one?
Implement search functionality	An index uid and a query	Full Text Search	The core component for all search operations.
Index a large dataset	An array of documents	Add Documents	Optimized for adding or updating items in bulk.
Index a single new item	A single document object	Add a Single Document	Perfect for real-time indexing as items are created.
Delete an item	A document_id	Delete a Document	Removes a specific document from your search index.
Set up a new search space	A uid and primaryKey	Create an Index	The first step for any new dataset you want to make searchable.
Improve search relevance	A list of synonym pairs	Update Synonyms	Helps Meilisearch understand related terms.

Component Details

This section provides detailed information for each Meilisearch component.

Full Text Search

Searches for documents matching a query within a given index.

INFO

This component requires your Meilisearch instance url and a Master Key for authentication, as detailed in the Getting Started section.

Inputs

Field	Required	Notes
url	required	The base URL of your Meilisearch instance.
index_uid	required	The unique identifier of the index to search in.
query	required	The search term or phrase.

Outputs

Field	Description
results	An array of document objects that match the search query.
response	The raw JSON response from the Meilisearch API, including metadata like hits, limit, etc.
headers	HTTP headers from the API response.

Use Case

Power a user-facing search bar. The user's input is passed to the query field, and the results are displayed back to the user.

{
  "component": "meilisearch.fullTextSearch",
  "url": "[https://my-instance.meilisearch.com](https://my-instance.meilisearch.com)",
  "index_uid": "products",
  "query": "retro t-shirt"
}

Troubleshooting

If you get a 404 Not Found error, ensure the index_uid is correct. If results is empty, check if your documents are indexed and searchable.

Create an Index

Creates a new search index. An index is a collection of documents that you can search through.

INFO

This component requires your Meilisearch instance url and a Master Key for authentication, as detailed in the Getting Started section.

Inputs

Field	Required	Notes
url	required	The base URL of your Meilisearch instance.
uid	required	The unique identifier for the new index (e.g., "movies", "products").
primaryKey	required	The attribute in your documents that serves as a unique identifier (e.g., "id", "sku").

Outputs

Field	Description
taskUid	The UID of the asynchronous task. Use this to track the status of the index creation.
response	The raw JSON response from the Meilisearch API.
headers	HTTP headers from the API response.

Use Case

When starting a new project, an agent can automatically create the necessary indexes (users, posts, products) in Meilisearch.

{
  "component": "meilisearch.createIndex",
  "url": "[https://my-instance.meilisearch.com](https://my-instance.meilisearch.com)",
  "uid": "users",
  "primaryKey": "user_id"
}

Troubleshooting

If you get an index_already_exists error, it means an index with that uid is already present. Index uids are unique.

Add a Single Document

Adds or updates a single document in a specified index. If the index doesn't exist, it will be created.

INFO

This component requires your Meilisearch instance url and a Master Key for authentication, as detailed in the Getting Started section.

Inputs

Field	Required	Notes
url	required	The base URL of your Meilisearch instance.
index_uid	required	The index where the document will be added.
body	optional	A JSON object representing the document to be added. This is configured in the component settings.

Outputs

Field	Description
taskUid	The UID of the asynchronous task for this indexing operation.
response	The raw JSON response from the Meilisearch API.
headers	HTTP headers from the API response.

Use Case

When a new user signs up on your platform, an agent can immediately index their profile information to make it searchable.

{
  "component": "meilisearch.addSingleDocument",
  "url": "[https://my-instance.meilisearch.com](https://my-instance.meilisearch.com)",
  "index_uid": "users",
  "body": {
    "user_id": 123,
    "name": "John Doe",
    "email": "john.doe@example.com"
  }
}

Troubleshooting

Ensure the document in the body contains the primaryKey field that was defined when the index was created.

Add Documents

Adds or updates a batch of documents in an index. This is more efficient than adding documents one by one.

INFO

This component requires your Meilisearch instance url and a Master Key for authentication, as detailed in the Getting Started section.

Inputs

Field	Required	Notes
url	required	The base URL of your Meilisearch instance.
uid	required	The index where the documents will be added.
body	optional	An array of JSON objects representing the documents. This is configured in the component settings.

Outputs

Field	Description
taskUid	The UID of the asynchronous task for this bulk indexing operation.
response	The raw JSON response from the Meilisearch API.
headers	HTTP headers from the API response.

Use Case

Run a nightly agent that fetches all new products from a database and adds them to your "products" index in a single batch operation.

{
  "component": "meilisearch.addDocuments",
  "url": "[https://my-instance.meilisearch.com](https://my-instance.meilisearch.com)",
  "uid": "products",
  "body": [
    { "id": 1, "name": "Laptop" },
    { "id": 2, "name": "Mouse" }
  ]
}

Troubleshooting

If the operation fails, check that every document in the array has the required primaryKey.

Update a Document

Adds a list of documents or updates them if they already exist in a specified index. If the provided index does not exist, it will be created automatically.

INFO

This component requires your Meilisearch instance url and a Master Key for authentication, as detailed in the Getting Started section.

Inputs

Field	Required	Notes
url	required	The base URL of your Meilisearch instance.
index_uid	required	The unique identifier of the index you want to use.
body	optional	An array of JSON objects representing the documents to add or update. This is configured in the component settings.

Outputs

Field	Description
taskUid	The UID of the asynchronous task for this indexing operation.
response	The raw JSON response from the Meilisearch API.
headers	HTTP headers from the API response.

Use Case

An agent syncs inventory data from an e-commerce platform to Meilisearch every hour, updating prices and stock levels.

{
  "component": "meilisearch.updateDocument",
  "url": "[https://my-instance.meilisearch.com](https://my-instance.meilisearch.com)",
  "index_uid": "inventory",
  "body": [
    { "sku": "t-shirt-red", "stock": 50, "price": 19.99 },
    { "sku": "t-shirt-blue", "stock": 35, "price": 21.99 }
  ]
}

Troubleshooting

This functions similarly to "Add Documents". Ensure each document in the body contains the primaryKey for the index.

Delete a Document

Deletes a single document from a specified index using its unique document ID.

INFO

This component requires your Meilisearch instance url and a Master Key for authentication, as detailed in the Getting Started section.

Inputs

Field	Required	Notes
url	required	The base URL of your Meilisearch instance.
index_uid	required	The index from which to delete the document.
document_id	required	The unique ID of the document to delete. This is the value of the primaryKey.

Outputs

Field	Description
taskUid	The UID of the asynchronous deletion task.
response	The raw JSON response from the Meilisearch API.
headers	HTTP headers from the API response.

Use Case

When a user deletes their account, an agent triggers this component to remove their corresponding document from the "users" index.

{
  "component": "meilisearch.deleteDocument",
  "url": "[https://my-instance.meilisearch.com](https://my-instance.meilisearch.com)",
  "index_uid": "users",
  "document_id": "123"
}

Troubleshooting

A document_not_found error will occur if a document with the given document_id does not exist in the index.

Update Synonyms

Updates the list of synonyms for an index to improve search relevance. Synonyms are normalized.

INFO

This component requires your Meilisearch instance url and a Master Key for authentication, as detailed in the Getting Started section.

Inputs

Field	Required	Notes
url	required	The base URL of your Meilisearch instance.
index_uid	required	The index whose synonyms you want to update.
body	optional	A JSON object where keys are words and values are arrays of their synonyms. Configured in settings.

Outputs

Field	Description
taskUid	The UID of the asynchronous task for this settings update.
response	The raw JSON response from the Meilisearch API.
headers	HTTP headers from the API response.

Use Case

To make searching for "pants" also return results for "trousers" and "slacks", update the synonyms for your clothing index.

{
  "component": "meilisearch.updateSynonyms",
  "url": "[https://my-instance.meilisearch.com](https://my-instance.meilisearch.com)",
  "index_uid": "clothes",
  "body": {
    "pants": ["trousers", "slacks"],
    "tshirt": ["tee", "t-shirt"]
  }
}

Troubleshooting

This operation overwrites existing synonyms. To add to the list, you must first fetch the current synonyms, append your new ones, and then send the complete list back.

Best Practices & Advanced Tips

• Use the SmythOS Vault: Your Meilisearch Master Key provides full administrative access. Always store it in the SmythOS Vault and never expose it directly in your components.
• Track Asynchronous Tasks: Most write operations in Meilisearch (add, update, delete) are asynchronous and return a taskUid. You can build logic in your agent to poll the Meilisearch Tasks API with this UID to confirm when an operation has been successfully processed.
• Batch Operations: For indexing large amounts of data, always use the Add Documents component instead of Add a Single Document in a loop. Batching is significantly more performant.
• Schema Design: Before indexing, carefully design the schema for your documents. Deciding on a consistent primaryKey and which fields should be searchable or filterable is crucial for a good search experience.
• Understand Filterable Attributes: To filter search results (e.g., by price, category), you must first configure those attributes as "filterable" in your Meilisearch index settings. This is another task that can be automated with an agent.

Troubleshooting Common Issues

• Error: 403 Forbidden

  • Cause: The API key used is incorrect or does not have sufficient permissions.
  • Solution: Verify that you are using the Master Key (not a search-only key) and that it is correctly stored and referenced from the SmythOS Vault.

• Error: 404 Not Found for an index

  • Cause: The index_uid you provided does not exist.
  • Solution: Double-check the spelling and case of your index_uid. You can use the Meilisearch Indexes API to list all existing indexes to confirm the name.

• Error: missing_document_id

  • Cause: You are trying to add a document that does not contain the field designated as the primaryKey for that index.
  • Solution: Ensure every document you send to Meilisearch includes the unique primaryKey field (e.g., id, sku, objectID).

• Search results are not updating after adding documents

  • Cause: Indexing is an asynchronous process. It might take a moment for new documents to become searchable.
  • Solution: Use the taskUid returned by write operations to check the status of the task. Only expect to find the document in search results after the task status is succeeded.

What's Next?

You're now equipped to integrate lightning-fast search into your automated workflows with the SmythOS Meilisearch Integration!

Consider these next steps:

• Build an Agent That...
  • Syncs your entire user database from PostgreSQL into a "users" index every night.
  • Listens for new blog posts on a WordPress site and automatically adds them to a "posts" index for your website's search bar.
  • Connects to a product information system, updates the "products" index in real-time as inventory changes, and uses Update Synonyms to improve product discovery.