Query structured spec data via REST or MCP. Get exactly what your agent needs.
{protocol}://{domain}:{port}
/experimental-features
Set the status of experimental features that can be toggled at runtime
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExperimentalSetRuntimeExperimentalFeaturesRequest"
},
"examples": {
"Example": {
"value": {
"metrics": false,
"vectorStore": true,
"exportPuffinReports": false
}
}
}
}
},
"required": true
}
PATCH /experimental-features
/indexes/{indexUid}
Update an index. Specify a primaryKey if it doesn't already exists yet.
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IndexesUpdateIndexPrimaryKeyRequest"
}
}
},
"required": true
}
PATCH /indexes/{indexUid}
/keys/{uid_or_key}
Update an API Key
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KeysUpdateApiKeyRequest"
},
"examples": {
"Patch an API Key Request": {
"value": {
"description": "Indexing Products API key"
}
}
}
}
}
}
PATCH /keys/{uid_or_key}
/indexes/{indexUid}/settings
Update the settings of an index. Updates in the settings route are partial. This means that any parameters not provided in the body will be left unchanged. [Learn more about the settings in this guide](https://docs.meilisearch.com/reference/features/settings.html). > info > If the provided index does not exist, it will be created.
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SettingsUpdateSettingsRequest"
},
"examples": {
"Example": {
"value": {
"faceting": {
"maxValuesPerFacet": 100,
"sortFacetValuesBy": {
"*": "alpha"
}
},
"synonyms": {
"wow": [
"world of warcraft"
],
"logan": [
"wolverine",
"xmen"
],
"wolverine": [
"xmen",
"logan"
]
},
"stopWords": [
"of",
"the",
"to"
],
"pagination": {
"maxTotalHits": 1000
},
"rankingRules": [
"words",
"typo",
"proximity",
"attribute",
"sort",
"exactness",
"release_date:asc"
],
"typoTolerance": {
"enabled": false,
"disableOnWords": [
"Tolkien"
],
"disableOnAttributes": [
"title",
"author"
],
"minWordSizeForTypos": {
"oneTypo": 4,
"twoTypos": 8
}
},
"distinctAttribute": "ean13",
"sortableAttributes": null,
"displayedAttributes": [
"title",
"description",
"genre",
"release_date"
],
"filterableAttributes": [],
"searchableAttributes": [
"title",
"description",
"genre"
]
}
}
}
}
},
"required": true
}
PATCH /indexes/{indexUid}/settings
/indexes/{indexUid}/settings/faceting
Update the faceting settings of an index. > info > If the provided index does not exist, it will be created.
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/faceting"
},
"examples": {}
}
},
"required": true,
"description": ""
}
PATCH /indexes/{indexUid}/settings/faceting
/indexes/{indexUid}/settings/pagination
Update the pagination configuration of an index. > info > If the provided index does not exist, it will be created.
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/pagination"
},
"examples": {}
}
},
"required": true,
"description": ""
}
PATCH /indexes/{indexUid}/settings/pagination
/indexes/{indexUid}/settings/typo-tolerance
Update the typo tolerance configuration of an index. > info > If the provided index does not exist, it will be created.
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/typoTolerance"
},
"examples": {}
}
},
"required": true,
"description": ""
}
PATCH /indexes/{indexUid}/settings/typo-tolerance
DocumentsAddOrUpdateBatchRequest
{
"type": "array",
"items": {
"description": "WARNING: Missing items property in array schema. Missing items property has been filled with this AnyType schema."
}
}
DocumentsAddOrUpdateBatchRequest1
{
"type": "array",
"items": {
"$ref": "#/components/schemas/document"
}
}
DocumentsDeleteSelectionBasedFilterRequest
{
"type": "object",
"properties": {
"filter": {
"$ref": "#/components/schemas/filter"
}
}
}
DocumentsDeleteSelectionByFilterRequest
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
},
"description": "An array of document ids to delete"
}
DocumentsGetByBatch200Response
{
"type": "object",
"required": [
"results",
"limit",
"offset",
"total"
],
"properties": {
"limit": {
"$ref": "#/components/schemas/limit"
},
"total": {
"$ref": "#/components/schemas/total"
},
"offset": {
"$ref": "#/components/schemas/offset"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/document"
}
}
}
}
DocumentsGetByBatchRequest
{
"type": "object",
"properties": {
"limit": {
"type": "number",
"default": 20,
"description": "Maximum number of documents returned."
},
"fields": {
"type": "array",
"items": {
"type": "string",
"default": "[\"*\"]",
"example": "[\"title\", \"overview\"]"
},
"description": "Array of attributes whose fields will be present in the returned documents. By default all attributes will be returned."
},
"filter": {
"$ref": "#/components/schemas/filter"
},
"offset": {
"type": "number",
"default": 0,
"description": "Number of documents to skip."
}
}
}
DocumentsGetByBatchResponse
{
"type": "object",
"required": [
"results",
"limit",
"offset",
"total"
],
"properties": {
"limit": {
"$ref": "#/components/schemas/limit"
},
"total": {
"$ref": "#/components/schemas/total"
},
"offset": {
"$ref": "#/components/schemas/offset"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/document"
}
}
}
}
ExperimentalRuntimeFeaturesGetResponse
{
"type": "object",
"required": [
"vectorStore",
"metrics",
"exportPuffinReports"
],
"properties": {
"metrics": {
"type": "boolean"
},
"vectorStore": {
"type": "boolean"
},
"exportPuffinReports": {
"type": "boolean"
}
}
}
ExperimentalSetRuntimeExperimentalFeaturesRequest
{
"type": "object",
"properties": {
"metrics": {
"type": "boolean"
},
"vectorStore": {
"type": "boolean"
},
"exportPuffinReports": {
"type": "boolean"
}
}
}
ExperimentalSetRuntimeExperimentalFeaturesResponse
{
"type": "object",
"required": [
"vectorStore",
"metrics",
"exportPuffinReports"
],
"properties": {
"metrics": {
"type": "boolean"
},
"vectorStore": {
"type": "boolean"
},
"exportPuffinReports": {
"type": "boolean"
}
}
}
HealthCheckMeilisearchInstanceResponse
{
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"enum": [
"available"
],
"type": "string"
}
}
}
IndexesCreateIndexRequest
{
"type": "object",
"required": [
"uid"
],
"properties": {
"uid": {
"type": "string"
},
"primaryKey": {
"type": "string"
}
}
}
IndexesListResponse
{
"type": "object",
"required": [
"results",
"limit",
"offset",
"total"
],
"properties": {
"limit": {
"$ref": "#/components/schemas/limit"
},
"total": {
"$ref": "#/components/schemas/total"
},
"offset": {
"$ref": "#/components/schemas/offset"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/index"
}
}
}
}
IndexesUpdateIndexPrimaryKeyRequest
{
"type": "object",
"required": [
"primaryKey"
],
"properties": {
"primaryKey": {
"type": "string"
}
}
}
KeysGetResponse
{
"type": "object",
"required": [
"results",
"limit",
"offset",
"total"
],
"properties": {
"limit": {
"$ref": "#/components/schemas/limit"
},
"total": {
"$ref": "#/components/schemas/total"
},
"offset": {
"$ref": "#/components/schemas/offset"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/key"
}
}
}
}
KeysUpdateApiKeyRequest
{
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
]
},
"description": {
"type": [
"string",
"null"
]
}
}
}
MultiSearchRequest
{
"type": "object",
"required": [
"queries"
],
"properties": {
"queries": {
"type": "array",
"items": {
"type": "object",
"examples": {
"Example": {
"value": {
"$ref": "#components/schemas/searchQuery/examples/Example/value",
"indexUid": "movies"
}
}
},
"required": [
"indexUid"
],
"properties": {
"$ref": "#/components/schemas/searchQuery/properties",
"indexUid": {
"type": "string",
"description": "The unique identifier of the index to be searched."
}
}
},
"description": "Array of the search queries to be performed."
}
}
}
MultiSearchResponse
{
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"$ref": "#/components/schemas/searchResponse/properties",
"indexUid": {
"type": "string",
"description": "The unique identifier of the searched index."
}
}
}
}
}
}
SettingsGetSettingsResponse
{
"type": "object",
"required": [
"rankingRules",
"distinctAttribute",
"searchableAttributes",
"displayedAttributes",
"stopWords",
"synonyms",
"filterableAttributes",
"sortableAttributes",
"typoTolerance",
"pagination",
"faceting"
],
"properties": {
"faceting": {
"$ref": "#/components/schemas/faceting"
},
"synonyms": {
"$ref": "#/components/schemas/synonyms"
},
"stopWords": {
"$ref": "#/components/schemas/stopWords"
},
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"rankingRules": {
"$ref": "#/components/schemas/rankingRules"
},
"typoTolerance": {
"$ref": "#/components/schemas/typoTolerance"
},
"distinctAttribute": {
"$ref": "#/components/schemas/distinctAttribute"
},
"sortableAttributes": {
"$ref": "#/components/schemas/sortableAttributes"
},
"displayedAttributes": {
"$ref": "#/components/schemas/displayedAttributes"
},
"filterableAttributes": {
"$ref": "#/components/schemas/filterableAttributes"
},
"searchableAttributes": {
"$ref": "#/components/schemas/searchableAttributes"
}
}
}
SettingsUpdateSettingsRequest
{
"type": "object",
"properties": {
"faceting": {
"$ref": "#/components/schemas/faceting"
},
"synonyms": {
"$ref": "#/components/schemas/synonyms"
},
"stopWords": {
"$ref": "#/components/schemas/stopWords"
},
"pagination": {
"$ref": "#/components/schemas/pagination"
},
"rankingRules": {
"$ref": "#/components/schemas/rankingRules"
},
"typoTolerance": {
"$ref": "#/components/schemas/typoTolerance"
},
"distinctAttribute": {
"$ref": "#/components/schemas/distinctAttribute"
},
"sortableAttributes": {
"$ref": "#/components/schemas/sortableAttributes"
},
"displayedAttributes": {
"$ref": "#/components/schemas/displayedAttributes"
},
"filterableAttributes": {
"$ref": "#/components/schemas/filterableAttributes"
},
"searchableAttributes": {
"$ref": "#/components/schemas/searchableAttributes"
}
}
}
StatsGetAllIndexesStatsResponse
{
"type": "object",
"required": [
"databaseSize",
"lastUpdate",
"indexes"
],
"properties": {
"indexes": {
"type": "object",
"properties": {
"indexUid": {
"$ref": "#/components/schemas/stats"
}
}
},
"lastUpdate": {
"$ref": "#/components/schemas/timestamp"
},
"databaseSize": {
"type": "number"
}
}
}
TasksGetAllResponse
{
"type": "object",
"required": [
"results",
"total",
"limit",
"from",
"next"
],
"properties": {
"from": {
"$ref": "#/components/schemas/from"
},
"next": {
"$ref": "#/components/schemas/next"
},
"limit": {
"$ref": "#/components/schemas/limit"
},
"total": {
"$ref": "#/components/schemas/total"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/task"
}
}
}
}
VersionGetMeilisearchVersionResponse
{
"type": "object",
"required": [
"commitSha",
"commitDate",
"pkgVersion"
],
"properties": {
"commitSha": {
"type": "string",
"example": "b46889b5f0f2f8b91438a08a358ba8f05fc09fc1"
},
"commitDate": {
"type": "string",
"example": "2021-07-08"
},
"pkgVersion": {
"type": "string",
"example": "0.1.1"
}
}
}
customRankingRuleDetails
{
"type": "object",
"required": [
"order",
"value"
],
"properties": {
"order": {
"$ref": "#/components/schemas/order"
},
"value": {
"type": [
"string",
"number",
"point"
],
"description": "The value that was used for sorting this document"
},
"distance": {
"type": "number",
"description": "The distance between the target point and the geoPoint in the document"
},
"similarity": {
"type": "number",
"description": "the similarity score between the target vector and the value vector.\n\n1.0 means a perfect similarity, 0.0 a perfect dissimilarity.\n"
}
},
"description": "Custom rule in the form of either `attribute:direction`, `vectorSort(vector)` or `_geoPoint(lat, lng):direction`."
}
dictionary
{
"type": "array",
"items": {
"type": "string"
},
"example": [
"J.K",
"Dr.",
"G/Box"
],
"description": "List of words on which the segmentation will be overridden."
}
displayedAttributes
{
"type": "array",
"items": {
"type": "string"
},
"example": [
"title",
"description",
"genre",
"release_date"
],
"description": "Fields displayed in the returned documents."
}
distinctAttribute
{
"type": "string",
"nullable": true,
"description": "Search returns documents with distinct (different) values of the given field."
}
document
{
"type": "object",
"example": {
"id": 25684,
"title": "American Ninja 5",
"poster": "https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg",
"overview": "When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.",
"release_date": 725846400
},
"description": "A document made of attribute. The maximum number of attribute for a document is 65,535.",
"additionalProperties": true
}
documentId
{
"oneOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"example": 468219
}
error
{
"type": "object",
"title": "error",
"required": [
"message",
"code",
"type",
"link"
],
"properties": {
"code": {
"type": "string"
},
"link": {
"type": "string"
},
"type": {
"type": "string"
},
"message": {
"type": "string"
}
},
"description": ""
}
facetHit
{
"type": "object",
"example": {
"count": 25,
"value": "Romance"
},
"properties": {
"count": {
"type": "integer",
"description": "The number of document containing the matched facet value."
},
"value": {
"type": "string",
"description": "The facet value being matched.",
"additionalProperties": true
}
},
"x-examples": [
{
"count": 25,
"value": "Romance"
}
],
"description": "FacetHit object represents a matched facet value for a facet search.",
"additionalProperties": true
}
facetSearchQuery
{
"type": "object",
"examples": {
"Example": {
"value": {
"facetName": "genres",
"facetQuery": "Romance"
}
}
},
"properties": {
"q": {
"type": "string",
"default": "\"\"",
"example": "\"Back to the future\"",
"description": "Additional search parameter. If additional search parameters are set, the method will return facet values that both: - Match the face query - Are contained in the records matching the additional search parameters"
},
"filter": {
"$ref": "#/components/schemas/filter"
},
"facetName": {
"type": "string",
"example": "\"genres\"",
"required": true,
"description": "Query string."
},
"facetQuery": {
"type": "string",
"default": "\"\"",
"example": "\"Horror\"",
"description": null
},
"matchingStrategy": {
"type": "string",
"default": "last",
"description": "Additional search parameter. If additional search parameters are set, the method will return facet values that both: - Match the face query - Are contained in the records matching the additional search parameters"
}
}
}
facetSearchResponse
{
"type": "object",
"title": "",
"required": [
"facetHits",
"facetQuery",
"processingTimeMs"
],
"properties": {
"facetHits": {
"type": "array",
"items": {
"$ref": "#/components/schemas/facetHit"
},
"description": "Array of facet hits"
},
"facetQuery": {
"type": "string",
"example": "ninja",
"description": "Facet query originating the response."
},
"processingTimeMs": {
"type": "integer",
"description": "Processing time of the facet search query."
}
}
}
faceting
{
"type": "object",
"properties": {
"maxValuesPerFacet": {
"type": "integer",
"default": 100,
"nullable": false,
"description": "Define maximum number of value returned for a facet for a **search query**. It means that with the default value of `100`, it is not possible to have `101` different colors if the `color`` field is defined as a facet at search time."
},
"sortFacetValuesBy": {
"type": "object",
"example": {
"*": "alpha",
"genres": "count"
},
"description": "Defines how facet values are sorted. By default, all facets (`*`) are sorted by name, alphanumerically in ascending order (`alpha`). `count` sorts facet values by the number of documents containing a facet value in descending order."
}
},
"description": "Customize faceting settings"
}
filter
{
"oneOf": [
{
"type": "array",
"items": {
"type": "string",
"pattern": "^[^:]+:[^:]+$"
}
},
{
"type": "string",
"pattern": "^[^:]+:[^:]+$",
"properties": {}
},
{
"type": "array",
"items": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "string"
}
]
}
}
],
"title": "filter",
"example": [
"director:Mati Diop",
[
"genres:Comedy",
"genres:Romance"
]
],
"description": "Attribute(s) to filter on.\n\nCan be made of 3 syntaxes\n\n- Nested Array: `[\"something > 1\", \"genres=comedy\", [\"genres=horror\", \"title=batman\"]]`\n- String: `\"something > 1 AND genres=comedy AND (genres=horror OR title=batman)\"`\n- Mixed: `[\"something > 1 AND genres=comedy\", \"genres=horror OR title=batman\"]`\n\n> info\n> _geoRadius({lat}, {lng}, {distance_in_meters}) and _geoBoundingBox([{lat, lng}], [{lat}, {lng}]) built-in filter rules can be used to filter documents within geo shapes.\n\n> warn\n> Attribute(s) used in `filter` should be declared as filterable attributes. See [Filtering and Faceted Search](https://docs.meilisearch.com/reference/features/filtering_and_faceted_search.html).\n"
}
filterableAttributes
{
"type": "array",
"items": {
"type": "string"
},
"title": "filterableAttributes",
"example": [
"genres",
"director"
],
"description": "Attributes to use for faceting and filtering. See [Filtering and Faceted Search](https://docs.meilisearch.com/reference/features/filtering_and_faceted_search.html).\n"
}
from
{
"type": "integer",
"example": 999,
"description": "The first task uid returned."
}
hit
{
"type": "object",
"example": {
"id": 25684,
"title": "American Ninja 5",
"poster": "https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg",
"overview": "When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.",
"_formatted": {
"id": 25684,
"title": "American Ninja 5",
"poster": "https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg",
"overview": "When a scientists daughter is kidnapped, American <em>Ninja</em>, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the <em>ninja</em>.",
"release_date": 725846400
},
"release_date": 725846400,
"_matchesPosition": {
"overview": [
{
"start": 49,
"length": 5
},
{
"start": 155,
"length": 5
}
]
}
},
"properties": {
"attribute": {
"type": [
"string",
"number"
],
"description": "Retrieve attributes of a search result. `attributesToRetrieve` controls these fields."
},
"_formatted": {
"type": "object",
"description": "Only present if `attributesToHighlight`/`attributesToCrop` is not empty. Return highlighted and cropped fields.",
"additionalProperties": true
},
"_geoDistance": {
"type": "number",
"description": "Using _geoPoint({lat}, {lng}) built-in sort rule at search leads the engine to return a _geoDistance within the search results. This field represents the distance in meters of the document from the specified _geoPoint."
},
"_rankingScore": {
"type": "number",
"description": "Only present if showRankingScore = `true`. The ranking score of that document."
},
"_matchesPosition": {
"type": "object",
"properties": {
"": {
"$ref": "#/components/schemas/matchesPosition"
}
},
"description": "Only present if showMatchesPosition = `true`. Array of all search query occurrences in all fields."
},
"_rankingScoreDetails": {
"type": "object",
"properties": {
"": {
"$ref": "#/components/schemas/rankingScoreDetails"
}
},
"description": "Only present if showRankingScoreDetails = `true`. The ranking score of each ranking rule for that document."
}
},
"x-examples": [
{
"id": 25684,
"title": "American Ninja 5",
"poster": "https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg",
"overview": "When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.",
"_formatted": {
"id": 25684,
"title": "American Ninja 5",
"poster": "https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg",
"overview": "When a scientists daughter is kidnapped, American <em>Ninja</em>, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the <em>ninja</em>.",
"release_date": 725846400
},
"release_date": 725846400,
"_matchesPosition": {
"overview": [
{
"start": 49,
"length": 5
},
{
"start": 155,
"length": 5
}
]
}
}
],
"description": "",
"additionalProperties": true
}
hitsPerPage
{
"type": "integer",
"example": 20,
"description": "Sets the number of results returned per page. If hitsPerPage is not provided as a query parameter, this parameter is ignored."
}
index
{
"type": "object",
"title": "",
"example": {
"uid": "movies",
"createdAt": "2019-11-20T09:40:33.711324Z",
"updatedAt": "2019-11-20T09:40:33.711324Z",
"primaryKey": "movie_id"
},
"required": [
"uid",
"createdAt",
"updatedAt"
],
"properties": {
"uid": {
"type": "string",
"example": "movies",
"description": "Unique identifier for the index"
},
"createdAt": {
"$ref": "#/components/schemas/timestamp"
},
"updatedAt": {
"$ref": "#/components/schemas/timestamp"
},
"primaryKey": {
"type": [
"string",
"null"
],
"example": "movie_id",
"nullable": true,
"description": "Custom primaryKey for documents"
}
},
"x-examples": [
{
"uid": "movies",
"createdAt": "2019-11-20T09:40:33.711324Z",
"updatedAt": "2019-11-20T09:40:33.711324Z",
"primaryKey": "movie_id"
}
],
"description": ""
}
key
{
"type": "object",
"title": "key",
"required": [
"actions",
"indexes",
"expiresAt"
],
"properties": {
"key": {
"type": "string",
"example": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
"readOnly": true,
"description": "The derived key to use in the Authorization header to authorize requests. Generated by Meilisearch with an HMAC, using an SHA-256 hash, of the uid and the master key."
},
"uid": {
"type": "string",
"example": "01b4bc42-eb33-4041-b481-254d00cce834",
"description": "A uuid v4 to identify the API Key. If not specified, it's generated by Meilisearch."
},
"name": {
"type": [
"string",
"null"
],
"default": null,
"description": "A human-readable name for the key. null if empty."
},
"actions": {
"type": "array",
"items": {
"enum": [
"search",
"documents.add",
"documents.get",
"documents.delete",
"indexes.create",
"indexes.get",
"indexes.update",
"indexes.delete",
"indexes.swap",
"tasks.get",
"tasks.cancel",
"tasks.delete",
"settings.get",
"settings.update",
"stats.get",
"metrics.get",
"dumps.create",
"snapshots.create",
"version",
"keys.get",
"keys.create",
"keys.update",
"keys.delete",
"experimental.get",
"experimental.update"
],
"type": "string",
"example": "documents.add"
},
"description": "A list of actions permitted for the key. [\"*\"] for all actions. The * character can be used as a wildcard when located at the last position. e.g. `documents.*` to authorize access on all documents endpoints.",
"uniqueItems": false
},
"indexes": {
"type": "array",
"items": {
"type": "string",
"example": "movies"
},
"description": "A list of accesible indexes permitted for the key. [\"*\"] for all indexes. The * character can be used as a wildcard when located at the last position. e.g. \"products_*\"\" to allow access to all indexes whose names start with \"products_\"."
},
"createdAt": {
"type": "string",
"example": "2021-11-12T10:00:00Z",
"readOnly": true,
"description": "Represent the date and time as RFC 3339 format when the API key has been created. Generated by Meilisearch."
},
"expiresAt": {
"type": [
"string",
"null"
],
"description": "Represent the expiration date and time as RFC 3339 format. null equals to no expiration time."
},
"updatedAt": {
"type": [
"string",
"null"
],
"default": null,
"readOnly": true,
"description": "Represent the date and time as RFC 3339 format when the API key has been updated. Generated by Meilisearch."
},
"description": {
"type": [
"string",
"null"
],
"default": null,
"description": "A description for the key. null if empty."
}
},
"description": "API keys are stored and managed by the master key holder and the default admin key holder. These are the keys used by the technical teams to interact with Meilisearch at the level of the client/server code. API keys can have restrictions on which methods can be accessed via an actions list; they can also expiresAt a specific date time and be restricted to a specific set of indexes."
}
limit
{
"type": "integer",
"example": 10,
"description": "Limit given for the query. If limit is not provided as a query parameter, this parameter displays the default limit value."
}
matchesPosition
{
"type": "object",
"required": [
"start",
"length"
],
"properties": {
"start": {
"type": "integer"
},
"length": {
"type": "integer"
}
},
"description": "Starting position and length in bytes of the matched term in the returned value"
}
next
{
"type": "integer",
"example": 989,
"description": "Represents the value to send in `from` to fetch the next slice of the results. The first item for the next slice starts at this exact number. When the returned value is null, it means that all the data have been browsed in the given order."
}
nonSeparatorTokens
{
"type": "array",
"items": {
"type": "string"
},
"example": [
"#",
"-",
"_"
],
"description": "List of tokens that will not be considered as word separators by Meilisearch."
}
offset
{
"type": "integer",
"example": 0,
"description": "Offset given for the query. If offset is not provided as a query parameter, this parameter displays the default offset value."
}
order
{
"type": "integer",
"description": "The order that this ranking rule was applied"
}
page
{
"type": "integer",
"example": 1,
"description": "Sets the specific results page to fetch. If page is not provided as a query parameter, this parameter is ignored."
}
pagination
{
"type": "object",
"properties": {
"maxTotalHits": {
"type": "integer",
"default": 1000,
"nullable": false,
"description": "Define the maximum number of documents reachable for a search request. It means that with the default value of `1000`, it is not possible to see the `1001`st result for a **search query**."
}
},
"description": "Customize pagination settings"
}
rankingRules
{
"type": "array",
"items": {
"type": "string"
},
"example": [
"words",
"typo",
"proximity",
"attribute",
"sort",
"exactness",
"release_date:asc"
],
"examples": [],
"description": "List of ranking rules sorted by order of importance. The order is customizable.\n\n[A list of ordered built-in ranking rules](https://docs.meilisearch.com/learn/core_concepts/relevancy.html).\n"
}
rankingScoreDetails
{
"type": "object",
"examples": {
"With sort": {
"typo": {
"order": 1,
"score": 1,
"typoCount": 0,
"maxTypoCount": 0
},
"words": {
"order": 0,
"score": 1,
"matchingWords": 7,
"maxMatchingWords": 7
},
"attribute": {
"order": 3,
"score": 1,
"query_word_distance_score": 1,
"attribute_ranking_order_score": 1
},
"exactness": {
"order": 6,
"score": 1,
"matchType": "exactMatch"
},
"proximity": {
"order": "2,",
"score": 1
},
"title:asc": {
"order": 4,
"value": "batman: the dark knight returns, part 1"
},
"release_date:desc": {
"order": 5,
"value": 1345507200
}
}
},
"properties": {
"typo": {
"type": "object",
"required": [
"order",
"typoCount",
"maxTypoCount",
"score"
],
"properties": {
"order": {
"$ref": "#/components/schemas/order"
},
"score": {
"$ref": "#/components/schemas/score"
},
"typoCount": {
"type": "integer",
"description": "The number of typos to correct in the query to match that document."
},
"maxTypoCount": {
"type": "integer",
"description": "The maximum number of typos that can be corrected in the query to match a document."
}
}
},
"words": {
"type": "object",
"required": [
"order",
"matchingWords",
"maxMatchingWords",
"score"
],
"properties": {
"order": {
"$ref": "#/components/schemas/order"
},
"score": {
"$ref": "#/components/schemas/score"
},
"matchingWords": {
"type": "integer",
"description": "number of words in the query that match in the document. The higher the better."
},
"maxMatchingWords": {
"type": "integer",
"description": "max number of words in the query that can match in the document for this iteration of the words ranking rule."
}
}
},
"attribute": {
"type": "object",
"required": [
"order",
"attributeRankingOrderScore",
"queryWordDistanceScore",
"score"
],
"properties": {
"order": {
"$ref": "#/components/schemas/order"
},
"score": {
"$ref": "#/components/schemas/score"
},
"queryWordDistanceScore": {
"type": "number",
"description": "Score computed depending on the position the attributes where each word of the query appears in.\n\nWords appearing in an attribute at the same position as in the query yield the highest score. The greater the distance to the position\nin the query, the lower the score.\n"
},
"attributeRankingOrderScore": {
"type": "number",
"description": "Score computed depending on the first attribute each word of the query appears in.\n\nThe first attribute in the `searchableAttributes` list yields the highest score, the last attribute the lowest.\n"
}
}
},
"exactness": {
"type": "object",
"required": [
"order",
"matchType",
"score"
],
"properties": {
"order": {
"$ref": "#/components/schemas/order"
},
"score": {
"$ref": "#/components/schemas/score"
},
"matchType": {
"type": "string",
"description": "One of `exactMatch`, `matchesStart` or `noExactMatch`.\n- `exactMatch`: the document contains an attribute that exactly matches the query.\n- `matchesStart`: the document contains an attribute that exactly starts with the query.\n- `noExactMatch`: any other document.\n"
},
"matchingWords": {
"type": "integer",
"description": "for `noExactMatch`, the number of exact words contained in an attribute. The higher the better.\n"
},
"maxMatchingWords": {
"type": "integer",
"description": "for `noExactMatch`, the maximum number of exact words contained in an attribute\n"
}
}
},
"proximity": {
"type": "object",
"required": [
"order",
"score"
],
"properties": {
"order": {
"$ref": "#/components/schemas/order"
},
"score": {
"$ref": "#/components/schemas/score"
}
}
}
},
"description": "The ranking score per ranking rule.",
"additionalProperties": {
"$ref": "#/components/schemas/customRankingRuleDetails"
}
}
score
{
"type": "number",
"description": "The relevancy score of a document according to a ranking rule and relative to a search query. Higher is better.\n\n`1.0` indicates a perfect match, `0.0` no match at all (Meilisearch should not return documents that don't match the query).\n"
}
searchQuery
{
"type": "object",
"examples": {
"Example": {
"value": {
"q": "Harry",
"limit": 20,
"facets": [
"genres",
"author"
],
"filter": "(genres = Horror AND genres = Mystery) OR release_date > 523242000",
"offset": 0,
"cropLength": 20,
"attributesToCrop": [
"overview"
],
"matchingStrategy": "all",
"showRankingScore": true,
"showMatchesPosition": true,
"attributesToRetrieve": [
"title",
"overview"
],
"attributesToHighlight": [
"overview"
],
"wordsMatchingStrategy": "all"
}
}
},
"properties": {
"q": {
"type": "string",
"default": "\"\"",
"example": "\"Back to the future\"",
"description": "Query string."
},
"page": {
"type": "number",
"example": 1,
"description": "The specific search results page to fetch."
},
"sort": {
"$ref": "#/components/schemas/sort"
},
"limit": {
"type": "number",
"default": 20,
"description": "Maximum number of documents returned."
},
"facets": {
"type": "array",
"items": {
"type": "string",
"default": "[]",
"example": "[\"genres\", \"author\"]"
},
"description": "Array of attributes whose fields will be distributed as a facet. If you have [set up filterableAttributes](https://docs.meilisearch.com/reference/features/settings.html#filterable-attributes), you can retrieve the count of matching terms for each [facets](https://docs.meilisearch.com/reference/features/filtering_and_faceted_search.html#faceted-search).[Learn more about facet distribution in the dedicated guide](https://docs.meilisearch.com/reference/features/search_parameters.html#facet-distribution)"
},
"filter": {
"$ref": "#/components/schemas/filter"
},
"offset": {
"type": "number",
"default": 0,
"description": "Number of documents to skip."
},
"vector": {
"type": "array",
"items": {
"description": "WARNING: Missing items property in array schema. Missing items property has been filled with this AnyType schema."
},
"default": "null",
"example": "[0.8, 0.145, 0.26, 0.3]",
"description": "Query vector."
},
"cropLength": {
"type": "number",
"default": 10,
"description": "Sets the total number of **words** to keep for the cropped part of an attribute specified in the `attributesToCrop` parameter."
},
"cropMarker": {
"type": "string",
"default": "…",
"description": "Sets the crop marker to apply before and/or after cropped part selected within an attribute defined in `attributesToCrop` parameter."
},
"hitsPerPage": {
"type": "number",
"example": 20,
"description": "Number of returned results per page."
},
"highlightPreTag": {
"type": "string",
"default": "<em>",
"example": "<mark>",
"description": "Specify the tag to put before the highlighted query terms."
},
"attributesToCrop": {
"type": "array",
"items": {
"type": "string",
"default": "[]",
"example": "[\"overview\", \"author\"]"
},
"description": "Array of attributes whose values have to be cropped. Cropped attributes are returned in `_formatted` response object."
},
"highlightPostTag": {
"type": "string",
"default": "</em>",
"example": "</mark>",
"description": "Specify the tag to put after the highlighted query terms."
},
"matchingStrategy": {
"type": "string",
"default": "last",
"description": "Defines which strategy to use to match the query terms within the documents as search results. Two different strategies are available, `last` and `all`. By default, the `last` strategy is chosen."
},
"showRankingScore": {
"type": "boolean",
"default": false,
"description": "Defines whether a `_rankingScore` number representing the relevancy score of that document should be returned or not."
},
"showMatchesPosition": {
"type": "boolean",
"default": false,
"description": "Defines whether an `_matchesPosition` object that contains information about the matches should be returned or not."
},
"attributesToRetrieve": {
"type": "array",
"items": {
"type": "string",
"default": "[\"*\"]",
"example": "[\"title\", \"overview\"]"
},
"description": "Array of attributes whose fields will be present in the returned documents. Defaults to the [displayedAttributes list](https://docs.meilisearch.com/reference/features/settings.html#displayed-attributes) which contains by default all attributes found in the documents."
},
"attributesToSearchOn": {
"type": "array",
"items": {
"description": "WARNING: Missing items property in array schema. Missing items property has been filled with this AnyType schema."
},
"default": "[\"*\"]",
"description": "Defines which `searchableAttributes` the query will search on."
},
"attributesToHighlight": {
"type": "array",
"items": {
"type": "string",
"default": "[]",
"example": "[\"title\", \"overview\"]"
},
"description": "Array of attributes whose values will contain highlighted matching terms. Highlighted attributes are returned in `_formatted` response object."
},
"showRankingScoreDetails": {
"type": "boolean",
"default": false,
"description": "Defines whether a `_rankingScoreDetails` object containing information about the score of that document for each ranking rule should be returned or not."
}
}
}
searchResponse
{
"type": "object",
"title": "",
"required": [
"hits",
"processingTimeMs",
"query"
],
"properties": {
"hits": {
"type": "array",
"items": {
"$ref": "#/components/schemas/hit"
},
"description": "Array of documents matching the search."
},
"page": {
"type": "integer",
"description": "The specific search results page to fetch."
},
"limit": {
"type": "integer",
"description": "Number of returned documents."
},
"query": {
"type": "string",
"example": "ninja",
"description": "Query originating the response."
},
"offset": {
"type": "integer",
"description": "Number of documents skipped."
},
"totalHits": {
"type": "integer",
"description": "Exhaustive total number of search results for the search query."
},
"facetStats": {
"type": "object",
"example": {
"price": {
"max": 4999.99,
"min": 1
}
},
"description": "When using the facets parameter, the distributed facets that contain some numeric values are displayed in a facetStats object that contains, per facet, the numeric min and max values of the hits returned by the search query. If none of the hits returned by the search query have a numeric value for a facet, this facet is not part of the facetStats object.\n",
"additionalProperties": {
"max": {
"type": "number",
"description": "The maximum value for the numerical facet being distributed."
},
"min": {
"type": "number",
"description": "The minimum value for the numerical facet being distributed."
},
"type": "object"
}
},
"totalPages": {
"type": "integer",
"description": "Number of navigatable results pages for the search query."
},
"hitsPerPage": {
"type": "integer",
"description": "Number of returned results per page."
},
"processingTimeMs": {
"type": "integer",
"description": "Processing time of the query."
},
"facetDistribution": {
"type": "object",
"example": {
"genres": {
"action": 273,
"comedy": 475,
"fantasy": 67,
"mystery": 70,
"thriller": 217,
"adventure": 132,
"animation": 118
}
},
"description": "[Distribution of the given facets](https://docs.meilisearch.com/reference/features/search_parameters.html#facet-distribution).\n",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
}
},
"estimatedTotalHits": {
"type": "integer",
"description": "Estimated number of candidates for the search query."
}
}
}
searchableAttributes
{
"type": "array",
"items": {
"type": "string"
},
"example": [
"title",
"description",
"genre"
],
"description": "Fields in which to search for matching query words sorted by order of importance."
}
separatorTokens
{
"type": "array",
"items": {
"type": "string"
},
"example": [
"&",
"</br>",
"@"
],
"description": "List of tokens that will be considered as word separators by Meilisearch."
}
settings
{
"type": "object",
"required": [
"synonyms",
"stopWords",
"rankingRules",
"filterableAttributes",
"distinctAttribute",
"searchableAttributes",
"displayedAttributes",
"typoTolerance"
],
"properties": {
"synonyms": {
"$ref": "#/components/schemas/synonyms"
},
"stopWords": {
"$ref": "#/components/schemas/stopWords"
},
"rankingRules": {
"$ref": "#/components/schemas/rankingRules"
},
"typoTolerance": {
"$ref": "#/components/schemas/typoTolerance"
},
"distinctAttribute": {
"$ref": "#/components/schemas/distinctAttribute"
},
"displayedAttributes": {
"$ref": "#/components/schemas/displayedAttributes"
},
"filterableAttributes": {
"$ref": "#/components/schemas/filterableAttributes"
},
"searchableAttributes": {
"$ref": "#/components/schemas/searchableAttributes"
}
},
"description": "[Learn more about the settings in this guide](https://docs.meilisearch.com/reference/features/settings.html).\n"
}
sort
{
"oneOf": [
{
"type": "array",
"items": {
"type": "string"
}
}
],
"title": "sort",
"example": [
"price:desc"
],
"description": "Fields on which you want to sort the results.\n\n> warn\n> Attribute(s) used in `sort` should be declared as sortable attributes. See [Sorting](https://docs.meilisearch.com/reference/features/sorting.html).\n\n> info\n> _geoPoint({lat}, {long}) built-in sort rule can be used to sort documents around a geo point.\n"
}
sortableAttributes
{
"type": "array",
"items": {
"type": "string"
},
"example": [
"price",
"author",
"title"
],
"description": "List of attributes to sort on at search."
}
stats
{
"type": "object",
"title": "",
"example": {
"isIndexing": true,
"fieldDistribution": {
"genre": 10,
"author": 9
},
"numberOfDocuments": 10
},
"required": [
"numberOfDocuments",
"isIndexing",
"fieldDistribution"
],
"properties": {
"isIndexing": {
"type": "boolean",
"description": "Whether or not the index is currently ingesting document"
},
"fieldDistribution": {
"type": "object",
"description": "How many documents contains a field",
"additionalProperties": {
"type": "integer"
}
},
"numberOfDocuments": {
"type": "integer",
"description": "Number of documents contained in the index."
}
},
"x-examples": [
{
"isIndexing": true,
"fieldDistribution": {
"genre": 10,
"author": 9
},
"numberOfDocuments": 10
}
]
}
stopWords
{
"type": "array",
"items": {
"type": "string"
},
"example": [
"of",
"the",
"to"
],
"description": "List of words ignored when present in search queries."
}
summarizedTask
{
"type": "object",
"examples": {
"documentAdditionOrUpdate": {
"$ref": "#/components/examples/202_documentAdditionOrUpdate"
}
},
"required": [
"uid",
"indexUid",
"status",
"type",
"enqueuedAt"
],
"properties": {
"type": {
"enum": [
"documentAdditionOrUpdate",
"documentDeletion",
"indexCreation",
"indexUpdate",
"indexDeletion",
"indexSwap",
"settingsUpdate",
"dumpCreation",
"taskCancelation",
"taskDeletion"
],
"type": "string",
"description": "The type of the task"
},
"status": {
"enum": [
"enqueued"
],
"type": "string",
"description": "The status of the task"
},
"taskUid": {
"type": "integer",
"description": "The unique sequential identifier of the task. This `taskUid` allows you to [track the current task](https://docs.meilisearch.com/reference/api/tasks.html)."
},
"indexUid": {
"type": "string",
"description": "The unique identifier of the index where this task is operated"
},
"enqueuedAt": {
"$ref": "#/components/schemas/timestamp",
"description": "Represent the date and time as a `RFC 3339` format when the task has been enqueued"
}
},
"description": "A summarized version of an asynchronous task. Summarized task representation are given for the 202 Accepted HTTP response. [Learn More](https://docs.meilisearch.com/learn/advanced/asynchronous_operations.html)."
}
swapIndexes
{
"type": "array",
"items": {
"$ref": "#/components/schemas/swapOperation"
},
"required": true,
"description": "Array of swap operations that will be processed atomically."
}
swapOperation
{
"type": "object",
"required": [
"indexes"
],
"properties": {
"indexes": {
"type": "array",
"items": {
"description": "WARNING: Missing items property in array schema. Missing items property has been filled with this AnyType schema."
},
"description": "The two indexUids to swap in the given operation."
}
}
}
synonyms
{
"type": "object",
"example": {
"wow": [
"world of warcraft"
],
"logan": [
"wolverine",
"xmen"
],
"wolverine": [
"xmen",
"logan"
]
},
"properties": {
"wow": {
"type": "array",
"items": {
"type": "string",
"example": "world of warcraft"
}
},
"logan": {
"type": "array",
"items": {
"type": "string",
"example": "wolverine"
}
},
"wolverine": {
"type": "array",
"items": {
"type": "string",
"example": "xmen"
}
}
},
"description": "List of associated words treated similarly. A word associated to an array of word as synonyms."
}
task
{
"type": "object",
"example": {
"uid": 0,
"type": "documentAdditionOrUpdate",
"status": "succeeded",
"details": {
"indexedDocuments": 10,
"receivedDocuments": 10
},
"duration": "PT5S",
"indexUid": "movies",
"startedAt": "2021-01-01T09:40:00.000000Z",
"canceledBy": null,
"enqueuedAt": "2021-01-01T09:39:00.000000Z",
"finishedAt": "2021-01-01T09:40:05.000000Z"
},
"required": [
"uid",
"indexUid",
"status",
"type",
"canceledBy",
"details",
"error",
"enqueuedAt",
"startedAt",
"finishedAt"
],
"properties": {
"uid": {
"type": "integer",
"description": "The unique sequential identifier of the task"
},
"type": {
"enum": [
"documentAdditionOrUpdate",
"documentDeletion",
"indexCreation",
"indexUpdate",
"indexDeletion",
"indexSwap",
"settingsUpdate",
"dumpCreation",
"taskCancelation",
"taskDeletion",
"snapshotCreation"
],
"type": "string",
"description": "The type of the task"
},
"error": {
"$ref": "#/components/schemas/error",
"description": "Error object containing error details and context when a task has a failed status."
},
"status": {
"enum": [
"enqueued",
"processing",
"succeeded",
"failed"
],
"type": "string",
"example": "succeeded",
"description": "The status of the task"
},
"details": {
"type": "object",
"properties": {
"dumpUid": {
"type": "string",
"description": "Identifier generated for the dump for dumpCreation task."
},
"settings": {
"$ref": "#/components/schemas/settings"
},
"primaryKey": {
"type": "string",
"description": "Value for the primaryKey field encountered if any for indexCreation or indexUpdate task."
},
"providedIds": {
"type": "integer",
"description": "Number of provided document ids for the documentDeletion task."
},
"deletedTasks": {
"type": "integer",
"description": "Number of tasks deleted for taskDeletion."
},
"matchedTasks": {
"type": "integer",
"description": "Number of tasks that match the request for taskCancelation or taskDeletion tasks."
},
"canceledTasks": {
"type": "integer",
"description": "Number of tasks canceled for taskCancelation."
},
"originalFilter": {
"type": "string",
"description": "Original filter query for taskCancelation or taskDeletion tasks."
},
"deletedDocuments": {
"type": "integer",
"description": "Number of documents finally deleted for documentDeletion and indexDeletion tasks."
},
"indexedDocuments": {
"type": "integer",
"description": "Number of documents finally indexed for documentAdditionOrUpdate task or a documentAdditionOrUpdate batch of tasks."
},
"receivedDocuments": {
"type": "integer",
"description": "Number of documents received for documentAdditionOrUpdate task."
}
},
"description": "Details information of the task payload."
},
"duration": {
"type": "string",
"nullable": true,
"description": "Total elasped time the engine was in processing state expressed as a `ISO-8601` duration format. Default is set to `null`"
},
"indexUid": {
"type": "string",
"description": "The unique identifier of the index where this task is operated"
},
"startedAt": {
"$ref": "#/components/schemas/timestamp",
"nullable": true,
"description": "Represent the date and time as a `RFC 3339` format when the task has been dequeued and started to be processed. Default is set to `null`"
},
"canceledBy": {
"type": "integer",
"description": "The uid of the task that performed the taskCancelation if the task has been canceled."
},
"enqueuedAt": {
"$ref": "#/components/schemas/timestamp",
"description": "Represent the date and time as a `RFC 3339` format when the task has been enqueued"
},
"finishedAt": {
"$ref": "#/components/schemas/timestamp",
"nullable": true,
"description": "Represent the date and time as a `RFC 3339` format when the task has failed or succeeded. Default is set to `null`"
}
},
"x-examples": [
{
"uid": 0,
"type": "documentAdditionOrUpdate",
"status": "succeeded",
"details": {
"indexedDocuments": 10,
"receivedDocuments": 10
},
"duration": "PT5S",
"indexUid": "movies",
"startedAt": "2021-01-01T09:40:00.000000Z",
"canceledBy": null,
"enqueuedAt": "2021-01-01T09:39:00.000000Z",
"finishedAt": "2021-01-01T09:40:05.000000Z"
}
],
"description": "Meilisearch is an asynchronous API. It means that the API does not behave as you would typically expect when handling the request's responses.\n\nSome operations are put in a queue and will be executed in turn (asynchronously). In this case, the server response contains the identifier to track the execution of the operation.\n\n[Learn More](https://docs.meilisearch.com/learn/advanced/asynchronous_operations.html).\n"
}
timestamp
{
"type": "string",
"example": "2019-11-20T09:40:33.711324Z",
"description": "An `RFC 3339` format for date/time/duration."
}
total
{
"type": "integer",
"example": 50,
"description": "Total number of browsable results using offset/limit parameters for the given resource."
}
totalHits
{
"type": "integer",
"example": 20,
"description": "Returns the total number of search results. Computed if either `page` or `hitsPerPage` is provided as a query parameter."
}
totalPages
{
"type": "integer",
"example": 20,
"description": "Returns the total number of navigatable results pages for the search query. Computed if either `page` or `hitsPerPage` is provided as a query parameter."
}
typoTolerance
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"default": true,
"nullable": false,
"description": "Enable the typo tolerance feature."
},
"disableOnWords": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"nullable": false,
"description": "Disable the typo tolerance feature for a set of query terms given for a search query."
},
"disableOnAttributes": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"nullable": false,
"description": "Disable the typo tolerance feature on the specified attributes."
},
"minWordSizeForTypos": {
"type": "object",
"properties": {
"oneTypo": {
"type": "integer",
"default": 5,
"nullable": false,
"description": "Customize the minimum size for a word to tolerate 1 typo."
},
"twoTypos": {
"type": "integer",
"default": 9,
"nullable": false,
"description": "Customize the minimum size for a word to tolerate 2 typos."
}
}
}
},
"description": "Customize typo tolerance feature."
}