Meilisearch Core API

Search engine API

www.meilisearch.com/docs/reference/api ↗

Version

1.7.0

OpenAPI

3.0.3

Endpoints

Schemas

85

Quality

Updated

3 days ago

Search search indexing full-text

Use this API in your AI agent

Query structured spec data via REST or MCP. Get exactly what your agent needs.

Get API Key

Server URLs

{protocol}://{domain}:{port}

Endpoints

Clear filters

GET POST PUT PATCH DELETE

Documents 4 endpoints

POST /indexes/{indexUid}/documents Add or replace documents

Add a list of documents or replace them if they already exist.

If you send an already existing document (same id) the whole existing document will be overwritten by the new document. Fields previously in the document not present in the new document are removed.

For a partial update of the document see Add or update documents route.

info
If the provided index does not exist, it will be created.

info
Use the reserved _geo object to add geo coordinates to a document. _geo is an object made of lat and lng field.

Use the reserved _vectors arrays of floats to add embeddings to a document. _vectors is an array of floats or multiple arrays of floats in an outer array.

operationId: Documents_addOrUpdateBatch

Parameters

Name	In	Required	Type	Description
indexUid	path	optional	string	Index Unique Identifier
primaryKey	query	optional	string	The primary key of the documents. primaryKey is optional. If you want to set the primary key of your index through this route, it only has to be done the first time you add documents to the index. After which it will be ignored if given.
csvDelimiter	query	optional	string	Customize the csv delimiter when importing CSV documents. By default its a comma “,”

Request Body

required

application/json

schema DocumentsAddOrUpdateBatchRequest

array

Responses

202

Accepted

401

Unauthorized

413

Payload Too Large

POST /indexes/{indexUid}/documents

POST /indexes/{indexUid}/documents/delete Delete documents

Delete a selection of documents based on a filter.

operationId: Documents_deleteSelectionBasedFilter

Parameters

Name	In	Required	Type	Description
indexUid	path	optional	string	Index Unique Identifier

Request Body

required

application/json

schema DocumentsDeleteSelectionBasedFilterRequest

Property	Type	Required
filter	object	optional

Responses

202

Accepted

401

Unauthorized

404

Not Found

POST /indexes/{indexUid}/documents/delete

POST /indexes/{indexUid}/documents/delete-batch Delete documents

Delete a selection of documents based on array of document id’s.

operationId: Documents_deleteSelectionByFilter

Parameters

Name	In	Required	Type	Description
indexUid	path	optional	string	Index Unique Identifier

Request Body

required

application/json

schema DocumentsDeleteSelectionByFilterRequest

array of ["string", "number"]

Responses

202

Accepted

401

Unauthorized

404

Not Found

POST /indexes/{indexUid}/documents/delete-batch

POST /indexes/{indexUid}/documents/fetch Get Documents

Get documents by batch.

operationId: Documents_getByBatch

Request Body

required

application/json

schema DocumentsGetByBatchRequest

Property	Type	Required
limit	number	optional
fields	array	optional
filter	object	optional
offset	number	optional

Responses

200

401

Unauthorized

404

Not Found

POST /indexes/{indexUid}/documents/fetch

Indexes 2 endpoints

POST /indexes Create Index

Create an index.

operationId: Indexes_createIndex

Request Body

required

application/json

schema IndexesCreateIndexRequest

Property	Type	Required
uid	string	required
primaryKey	string	optional

Responses

202

Accepted

400

Bad Request

401

Unauthorized

POST /indexes

POST /swap-indexes Swap Indexes

Deploy a new version of an index without any downtime for clients by swapping documents, settings, and task history between two indexes. Specifying several swap operations that will be processed in an atomic way is possible.

operationId: Indexes_swapIndexes

Parameters

Name	In	Required	Type	Description
taskUid	path	optional	integer	The task identifier

Request Body

application/json

schema swapIndexes

array of object

Property	Type	Required
indexes	array	required

Responses

202

Accepted

401

Unauthorized

POST /swap-indexes

Keys 1 endpoints

POST /keys Create an API Key

operationId: Keys_createApiKey

Request Body

application/json

schema key

Property	Type	Required
key	string	optional
uid	string	optional
name	["string", "null"]	optional
actions	array	required
indexes	array	required
createdAt	string	optional
expiresAt	["string", "null"]	required
updatedAt	["string", "null"]	optional
description	["string", "null"]	optional

Responses

200

POST /keys

Search 3 endpoints

POST /indexes/{indexUid}/facet-search Facet Search

Search for facet values matching a specific query for a facet. When many values exist for a facet, users need to be able to discover non-show values they can select in order to refine their faceted search.

operationId: Search_facetValuesQuery

Parameters

Name	In	Required	Type	Description
indexUid	path	optional	string	Index Unique Identifier

Request Body

required

application/json

schema facetSearchQuery

Property	Type	Required
q	string	optional
filter	object	optional
facetName	string	optional
facetQuery	string	optional
matchingStrategy	string	optional

Responses

200

401

Unauthorized

404

Not Found

POST /indexes/{indexUid}/facet-search

POST /indexes/{indexUid}/search Search

Search for documents matching a specific query in the given index.

This is the preferred route to perform search when an API key is required, as it allows for preflight requests to be cached. Caching preflight requests improves considerably the speed of the search.

operationId: Search_documentsSearch

Parameters

Name	In	Required	Type	Description
indexUid	path	optional	string	Index Unique Identifier

Request Body

required

application/json

schema searchQuery

Property	Type	Required
q	string	optional
page	number	optional
sort	object	optional
limit	number	optional
facets	array	optional
filter	object	optional
offset	number	optional
vector	array	optional
cropLength	number	optional
cropMarker	string	optional
hitsPerPage	number	optional
highlightPreTag	string	optional
attributesToCrop	array	optional
highlightPostTag	string	optional
matchingStrategy	string	optional
showRankingScore	boolean	optional
showMatchesPosition	boolean	optional
attributesToRetrieve	array	optional
attributesToSearchOn	array	optional
attributesToHighlight	array	optional
…1 more	object	optional

Responses

200

401

Unauthorized

404

Not Found

POST /indexes/{indexUid}/search

POST /multi-search Multi Search

Make multiple search queries in a single HTTP request.

The queries can span different indexes or lookup the results of different filters on the same index. Each query has its own results set.

operationId: multi_search

Request Body

required

application/json

schema MultiSearchRequest

Property	Type	Required
queries	array	required
└ indexUid	string	required

Responses

200

401

Unauthorized

POST /multi-search

Tasks 1 endpoints

POST /tasks/cancel Cancel tasks

Cancel enqueued and/or processing tasks

operationId: Tasks_cancelOperation

Parameters

Name	In	Required	Type	Description
uids	query	optional	number	Permits to filter tasks by their uid. By default, when the `uids` query parameter is not set, all task uids are returned. It’s possible to specify several uids by separating them with the `,` character.
indexUids	query	optional	string	Permits to filter tasks by their related index. By default, when `indexUids` query parameter is not set, the tasks of all the indexes are returned. It is possible to specify several indexes by separating them with the `,` character.
statuses	query	optional	string	Permits to filter tasks by their status. By default, when `statuses` query parameter is not set, all task statuses are returned. It’s possible to specify several statuses by separating them with the `,` character.
types	query	optional	string	Permits to filter tasks by their related type. By default, when `types` query parameter is not set, all task types are returned. It’s possible to specify several types by separating them with the `,` character.
canceledBy	query	optional	string	Permits to filter tasks using the uid of the task that canceled them. It’s possible to specify several task uids by separating them with the `,` character.
beforeEnqueuedAt	query	optional	string	Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued before the given date. Supports RFC 3339 date format.
afterEnqueuedAt	query	optional	string	Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued after the given date. Supports RFC 3339 date format.
beforeStartedAt	query	optional	string	Permits to filter tasks based on their startedAt time. Matches tasks started before the given date. Supports RFC 3339 date format.
afterStartedAt	query	optional	string	Permits to filter tasks based on their startedAt time. Matches tasks started after the given date. Supports RFC 3339 date format.
beforeFinishedAt	query	optional	string	Permits to filter tasks based on their finishedAt time. Matches tasks finished before the given date. Supports RFC 3339 date format.
afterFinishedAt	query	optional	string	Permits to filter tasks based on their finishedAt time. Matches tasks finished after the given date. Supports RFC 3339 date format.

Responses

202

Accepted

400

Bad Request

401

Unauthorized

POST /tasks/cancel

Load more endpoints

Schemas

array DocumentsAddOrUpdateBatchRequest

{
  "type": "array",
  "items": {
    "description": "WARNING: Missing items property in array schema. Missing items property has been filled with this AnyType schema."
  }
}

array DocumentsAddOrUpdateBatchRequest1

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/document"
  }
}

object DocumentsDeleteSelectionBasedFilterRequest

{
  "type": "object",
  "properties": {
    "filter": {
      "$ref": "#/components/schemas/filter"
    }
  }
}

array DocumentsDeleteSelectionByFilterRequest

{
  "type": "array",
  "items": {
    "type": [
      "string",
      "number"
    ]
  },
  "description": "An array of document ids to delete"
}

object 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"
      }
    }
  }
}

object 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."
    }
  }
}

object 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"
      }
    }
  }
}

object ExperimentalRuntimeFeaturesGetResponse

{
  "type": "object",
  "required": [
    "vectorStore",
    "metrics",
    "exportPuffinReports"
  ],
  "properties": {
    "metrics": {
      "type": "boolean"
    },
    "vectorStore": {
      "type": "boolean"
    },
    "exportPuffinReports": {
      "type": "boolean"
    }
  }
}

object ExperimentalSetRuntimeExperimentalFeaturesRequest

{
  "type": "object",
  "properties": {
    "metrics": {
      "type": "boolean"
    },
    "vectorStore": {
      "type": "boolean"
    },
    "exportPuffinReports": {
      "type": "boolean"
    }
  }
}

object ExperimentalSetRuntimeExperimentalFeaturesResponse

{
  "type": "object",
  "required": [
    "vectorStore",
    "metrics",
    "exportPuffinReports"
  ],
  "properties": {
    "metrics": {
      "type": "boolean"
    },
    "vectorStore": {
      "type": "boolean"
    },
    "exportPuffinReports": {
      "type": "boolean"
    }
  }
}

object HealthCheckMeilisearchInstanceResponse

{
  "type": "object",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "enum": [
        "available"
      ],
      "type": "string"
    }
  }
}

object IndexesCreateIndexRequest

{
  "type": "object",
  "required": [
    "uid"
  ],
  "properties": {
    "uid": {
      "type": "string"
    },
    "primaryKey": {
      "type": "string"
    }
  }
}

object 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"
      }
    }
  }
}

object IndexesUpdateIndexPrimaryKeyRequest

{
  "type": "object",
  "required": [
    "primaryKey"
  ],
  "properties": {
    "primaryKey": {
      "type": "string"
    }
  }
}

object 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"
      }
    }
  }
}

object KeysUpdateApiKeyRequest

{
  "type": "object",
  "properties": {
    "name": {
      "type": [
        "string",
        "null"
      ]
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}

object 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": {
          "indexUid": {
            "type": "string",
            "description": "The unique identifier of the index to be searched."
          }
        }
      },
      "description": "Array of the search queries to be performed."
    }
  }
}

object MultiSearchResponse

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "indexUid": {
            "type": "string",
            "description": "The unique identifier of the searched index."
          }
        }
      }
    }
  }
}

object 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"
    }
  }
}

object 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"
    }
  }
}

object 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"
    }
  }
}

object 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"
      }
    }
  }
}

object 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"
    }
  }
}

object 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`."
}

array dictionary

{
  "type": "array",
  "items": {
    "type": "string"
  },
  "example": [
    "J.K",
    "Dr.",
    "G/Box"
  ],
  "description": "List of words on which the segmentation will be overridden."
}

array displayedAttributes

{
  "type": "array",
  "items": {
    "type": "string"
  },
  "example": [
    "title",
    "description",
    "genre",
    "release_date"
  ],
  "description": "Fields displayed in the returned documents."
}

string distinctAttribute

{
  "type": "string",
  "nullable": true,
  "description": "Search returns documents with distinct (different) values of the given field."
}

object 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
}

object documentId

{
  "oneOf": [
    {
      "type": "number"
    },
    {
      "type": "string"
    }
  ],
  "example": 468219
}

object error

{
  "type": "object",
  "title": "error",
  "required": [
    "message",
    "code",
    "type",
    "link"
  ],
  "properties": {
    "code": {
      "type": "string"
    },
    "link": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "description": ""
}

object 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
}

object 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\"",
      "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"
    }
  }
}

object 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."
    }
  }
}

object 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"
}

object 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"
}

array 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"
}

integer from

{
  "type": "integer",
  "example": 999,
  "description": "The first task uid returned."
}

object 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
}

integer 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."
}

object 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": ""
}

object 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."
}

integer 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."
}

object 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"
}

integer 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."
}

array nonSeparatorTokens

{
  "type": "array",
  "items": {
    "type": "string"
  },
  "example": [
    "#",
    "-",
    "_"
  ],
  "description": "List of tokens that will not be considered as word separators by Meilisearch."
}

integer 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."
}

integer order

{
  "type": "integer",
  "description": "The order that this ranking rule was applied"
}

integer 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."
}

object 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"
}

array 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"
}

Load more schemas

Versions

Version	Endpoints	Schemas	Ingested	Status
1.7.0	73	71	2026-05-11	current
1.7.0	73	71	2026-04-16

Meilisearch Core API

Server URLs

Endpoints

Documents 4 endpoints

Parameters

Request Body

Responses

Parameters

Request Body

Responses

Parameters

Request Body

Responses

Request Body

Responses

Dumps 1 endpoints

Responses

Indexes 2 endpoints

Request Body

Responses

Parameters

Request Body

Responses

Keys 1 endpoints

Request Body

Responses

Search 3 endpoints

Parameters

Request Body

Responses

Parameters

Request Body

Responses

Request Body

Responses

Snapshots 1 endpoints

Responses

Tasks 1 endpoints

Parameters

Responses

Schemas

Versions