curl \
-X POST 'MEILISEARCH_URL/indexes/movies/search' \
-H 'Authorization: Bearer API_KEY' \
-H 'Content-Type: application/json' \
--data-binary '{ "q": "american ninja" }'{
"hits": [
{
"id": 2770,
"title": "American Pie 2",
"poster": "https://image.tmdb.org/t/p/w1280/q4LNgUnRfltxzp3gf1MAGiK5LhV.jpg",
"overview": "The whole gang are back and as close as ever. They decide to get even closer by spending the summer together at a beach house. They decide to hold the biggest…",
"release_date": 997405200
},
{
"id": 190859,
"title": "American Sniper",
"poster": "https://image.tmdb.org/t/p/w1280/svPHnYE7N5NAGO49dBmRhq0vDQ3.jpg",
"overview": "U.S. Navy SEAL Chris Kyle takes his sole mission—protect his comrades—to heart and becomes one of the most lethal snipers in American history. His pinpoint accuracy not only saves countless lives but also makes him a prime…",
"release_date": 1418256000
}
],
"offset": 0,
"limit": 2,
"estimatedTotalHits": 976,
"processingTimeMs": 35,
"query": "american "
}{
"message": "The Authorization header is missing. It must use the bearer authorization method.",
"code": "missing_authorization_header",
"type": "auth",
"link": "https://docs.meilisearch.com/errors#missing_authorization_header"
}{
"message": "Index `movies` not found.",
"code": "index_not_found",
"type": "invalid_request",
"link": "https://docs.meilisearch.com/errors#index_not_found"
}Search with POST
Search for documents matching a query in the given index.
Equivalent to the search with GET route in the Meilisearch API.
Note: By default this endpoint returns at most 1000 results. Configure pagination.maxTotalHits in index settings to change this limit.
curl \
-X POST 'MEILISEARCH_URL/indexes/movies/search' \
-H 'Authorization: Bearer API_KEY' \
-H 'Content-Type: application/json' \
--data-binary '{ "q": "american ninja" }'{
"hits": [
{
"id": 2770,
"title": "American Pie 2",
"poster": "https://image.tmdb.org/t/p/w1280/q4LNgUnRfltxzp3gf1MAGiK5LhV.jpg",
"overview": "The whole gang are back and as close as ever. They decide to get even closer by spending the summer together at a beach house. They decide to hold the biggest…",
"release_date": 997405200
},
{
"id": 190859,
"title": "American Sniper",
"poster": "https://image.tmdb.org/t/p/w1280/svPHnYE7N5NAGO49dBmRhq0vDQ3.jpg",
"overview": "U.S. Navy SEAL Chris Kyle takes his sole mission—protect his comrades—to heart and becomes one of the most lethal snipers in American history. His pinpoint accuracy not only saves countless lives but also makes him a prime…",
"release_date": 1418256000
}
],
"offset": 0,
"limit": 2,
"estimatedTotalHits": 976,
"processingTimeMs": 35,
"query": "american "
}{
"message": "The Authorization header is missing. It must use the bearer authorization method.",
"code": "missing_authorization_header",
"type": "auth",
"link": "https://docs.meilisearch.com/errors#missing_authorization_header"
}{
"message": "Index `movies` not found.",
"code": "index_not_found",
"type": "invalid_request",
"link": "https://docs.meilisearch.com/errors#index_not_found"
}Authorizations
An API key is a token that you provide when making API calls. Read more about how to secure your project.
Include the API key to the Authorization header, for instance:
-H 'Authorization: Bearer 6436fc5237b0d6e0d64253fbaac21d135012ecf1'
If you use a SDK, ensure you instantiate the client with the API key, for instance with JS SDK:
const client = new MeiliSearch({
host: 'MEILISEARCH_URL',
apiKey: '6436fc5237b0d6e0d64253fbaac21d135012ecf1'
});
Path Parameters
Unique identifier of the index.
Body
Sets the search terms.
Meilisearch returns documents that match this query.
The query supports prefix search and typo tolerance.
Meilisearch only considers the first ten words; terms are normalized (lowercase, accents ignored).
Omit or leave empty for a placeholder search: no query terms are applied, so Meilisearch returns all searchable documents in the index, ordered by ranking rules.
Enclose terms in double quotes (") for phrase search: only documents containing that exact sequence of words are returned (e.g. "Winter Feast").
Use a minus sign (-) before a word or phrase to exclude it from results.
Number of documents to skip at the start of the results.
Use together with limit for pagination (e.g. offset=20 and limit=20 returns results 21–40).
This parameter is ignored when page or hitsPerPage is set; in that case the response includes totalHits and totalPages instead of estimatedTotalHits.
x >= 0Maximum number of documents to return in the response.
Use with offset for pagination.
This parameter is ignored when page or hitsPerPage is set. The value cannot exceed the index maxTotalHits setting.
x >= 0Request a specific results page (1-indexed).
Use together with hitsPerPage.
When this parameter is set, the response includes totalHits and totalPages instead of estimatedTotalHits.
page and hitsPerPage take precedence over offset and limit.
x >= 0Maximum number of documents per page for pagination.
This value determines totalPages; use it together with page.
When set, the response includes totalHits and totalPages.
Set to 0 to obtain the exhaustive totalHits count without returning any documents.
x >= 0List of attributes to include in each returned document.
Use ["*"] to return all attributes; if not set, the index displayed attributes list is used.
Attributes that are not in displayedAttributes are omitted from the response.
Attributes whose values should be cropped to a short excerpt.
The cropped text appears in each hit's _formatted object.
Length is controlled by cropLength, or you can override it per attribute with the attribute:length syntax.
Use ["*"] to crop all attributes in attributesToRetrieve.
When possible, the crop is centered around the matching terms.
Maximum number of words to include in cropped values.
This parameter only applies when attributesToCrop is set.
Both query terms and stop words count toward this length.
x >= 0String used to mark crop boundaries in cropped text.
If null or empty, no markers are inserted.
Markers are only added where content was actually removed.
Attributes in which matching query terms should be highlighted.
The highlighted text appears in each hit's _formatted object.
Use ["*"] to highlight in all attributes from attributesToRetrieve.
By default, matches are wrapped in <em> and </em>; you can override this with highlightPreTag and highlightPostTag.
Highlighting also applies to synonyms and stop words.
Supported value types are string, number, array, and object.
Note: highlights matches within all listed attributes, even those not in searchableAttributes.
String to insert before each highlighted term.
Can be any string (e.g. <strong>, *).
If null or empty, nothing is inserted at the start of a match.
String to insert after each highlighted term.
Should be used together with highlightPreTag to avoid malformed output (e.g. unclosed HTML tags).
When true, each hit includes a _matchesPosition object with the byte offset (start and length) of each matched term.
This is useful when you need custom highlighting.
Note: reports match positions in all attributes, even non-searchable ones. Positions are measured in bytes, not characters.
A filter expression to narrow results.
All attributes used in the expression must be in filterableAttributes.
You can pass a string (e.g. "(genres = horror OR genres = mystery) AND director = 'Jordan Peele'") or an array (e.g. [["genres = horror", "genres = mystery"], "director = 'Jordan Peele'"]).
For geo search, use _geoRadius(lat, lng, distance_in_meters), _geoBoundingBox([lat,lng],[lat,lng]), or _geoPolygon([lat,lng], ...) (GeoJSON only for polygon).
Sort results by one or more attributes and their order.
Use the format ["attribute:asc", "attribute:desc"]; only attributes in sortableAttributes can be used.
For geo search, use _geoPoint(lat,lng):asc or :desc; the response then includes _geoDistance in meters.
The first attribute in the list has precedence.
Return only one document per distinct value of the given attribute (e.g. deduplicate by product_id).
The attribute must be in filterableAttributes.
This overrides the index distinctAttribute setting for this request.
See distinct attribute.
Return the count of matches per facet value for the listed attributes.
The response includes facetDistribution and, for numeric facets, facetStats (min/max).
This route also supports patterns, i.e., "title", "dogs.", "", which can match over the filterableAttributes.
The number of values returned per facet is limited by the index maxValuesPerFacet setting; attributes not in filterableAttributes are ignored.
More info: faceting.
"[\"*\", \"title\", \"description_*\", \"*_date\", \"*content*\"]"
How to match query terms when there are not enough results to satisfy limit.
last: Returns documents containing all query terms first. If there are not enough such results, Meilisearch removes one query term at a time, starting from the end of the query (e.g. for "big fat cat", then "big fat", then "big").
all: Only returns documents that contain all query terms. Meilisearch does not relax the query even if fewer than limit documents match.
frequency: Returns documents containing all query terms first. If there are not enough, removes one term at a time starting with the word that is most frequent in the dataset, giving more weight to rarer terms (e.g. in "white cotton shirt", prioritizes documents containing "white" if "shirt" is very common).
Default: last.
last, all, frequency Restrict the search to the listed attributes only.
Each attribute must be in the index searchable attributes list.
The order of attributes in this parameter does not affect relevancy.
Stop the search at the first document whose ranking score is below this value (between 0.0 and 1.0). All the documents after this document are excluded from the hits.
Excluded hits do not count toward estimatedTotalHits, totalHits, or facet distribution.
When used together with page and hitsPerPage, this parameter may reduce performance because Meilisearch must score all matching documents.
Explicitly specify the language(s) of the query.
Pass an array of supported ISO-639 locales.
This overrides auto-detection; use it when auto-detection is wrong for the query or the documents.
See also the localizedAttributes settings and Language.
af, ak, am, ar, az, be, bn, bg, ca, cs, da, de, cy, el, en, eo, et, fi, fr, gu, he, hi, hr, hu, hy, id, it, jv, ja, kn, ka, km, ko, la, lv, lt, ml, mr, mk, my, ne, nl, nb, or, pa, fa, pl, pt, ro, ru, si, sk, sl, sn, es, sr, sv, ta, te, tl, th, tk, tr, uk, ur, uz, vi, yi, zh, zu, afr, aka, amh, ara, aze, bel, ben, bul, cat, ces, dan, deu, cym, ell, eng, epo, est, fin, fra, guj, heb, hin, hrv, hun, hye, ind, ita, jav, jpn, kan, kat, khm, kor, lat, lav, lit, mal, mar, mkd, mya, nep, nld, nob, ori, pan, pes, pol, por, ron, rus, sin, slk, slv, sna, spa, srp, swe, tam, tel, tgl, tha, tuk, tur, ukr, urd, uzb, vie, yid, zho, zul, cmn Hybrid search: combines keyword and semantic search.
The embedder field (required) must match an embedder name in index settings.
The semanticRatio field controls the balance: 0.0 means keyword-only results, 1.0 means semantic-only.
When q is empty and semanticRatio is greater than 0, Meilisearch performs a pure semantic search.
The semanticRatio field defaults to 0.5. A value of 0.0 uses keyword-only results; 1.0 uses semantic-only results.
Show child attributes
Show child attributes
Custom query vector for vector or hybrid search.
The array length must match the dimensions of the embedder configured in the index.
This parameter is mandatory when using a user-provided embedder.
When used with hybrid, documents are ranked by vector similarity.
You can also use it to override an embedder's automatic vector generation.
When true, the response includes document and query embeddings in each hit's _vectors field.
The _vectors field must be listed in displayedAttributes for it to appear.
For multimodal search: provide data (e.g. image, text) that populates a single search fragment configured in index settings.
A search fragment is a named slot that defines which media or fields are sent to the embedder.
An embedder is required; this parameter is incompatible with vector.
POST only.
Personalized search: provide an object with a userContext field (a string describing the user, e.g. preferences or behavior).
Results are then tailored to that profile.
Personalization must be enabled (e.g. Cohere key for self-hosted instances).
Show child attributes
Show child attributes
When true, runs the query on the whole network (all shards covered exactly once).
When false, the query runs locally.
When omitted or null, the default value depends on whether the sharding is enabled for the instance:
- If the instance has sharding enabled (has a leader), defaults to
true. - Otherwise defaults to
false.
It also requires the network experimental feature.
Values: true = use the whole network; false = local, default = see above.
When using the network, the index must exist with compatible settings on all remotes.
When true, each document includes a _rankingScore between 0.0 and 1.0; a higher value means the document is more relevant.
See ranking score.
The sort ranking rule does not affect the value of _rankingScore.
When true, each document includes _rankingScoreDetails, which breaks down the score contribution of each ranking rule.
Useful for debugging relevancy.
When true, the response includes a performanceDetails object with a timing breakdown of the query processing.
An inline search rule to apply to this query.
- Requires the
dynamicSearchRuleexperimental feature - Inline rules require the Enterprise Edition of Meilisearch.
Show child attributes
Show child attributes
Response
The documents are returned.
- Option 1
- Option 2
Search response containing matching documents and metadata.
Number of results per page.
x >= 0Current page index (1-based).
x >= 0Exhaustive total number of result pages.
x >= 0Exhaustive total number of matching documents.
x >= 0Matching documents.
Each hit contains document fields and, when requested, _formatted, _matchesPosition, _rankingScore, _rankingScoreDetails, _geoDistance.
Show child attributes
Show child attributes
Query string that produced this response.
Time taken to process the query, in milliseconds.
x >= 0Query embedding used for the search.
Present when vector or hybrid search was used.
Count of matching documents per facet value for each requested facet.
Present when facets was set.
Show child attributes
Show child attributes
Minimum and maximum numeric values per facet.
Present for numeric facets when facets was set.
Show child attributes
Show child attributes
UUID v7 identifying this search request.
Query and index metadata.
Present when requested via the Meili-Include-Metadata header.
Show child attributes
Show child attributes
Timing breakdown per processing step.
Present when showPerformanceDetails was true.
Errors from remote shards. Federated search only.
Show child attributes
Show child attributes
Exhaustive number of semantic search matches.
AI-powered (hybrid/semantic) searches only.
x >= 0