Meilisearch Core API
0.30.0

Search documents, configure and manage the Meilisearch engine.

This is the documentation for version 0.30.0 of the API. Last update on Nov 29, 2022.

This API is provided under license MIT.

Base URL 
https://example.meilisearch.com:7700

Authentication

Api key (http)

An API key is a token that you provide when making API calls. Include the token in a header parameter called Authorization.

Example: Authorization: Bearer 8fece4405662dd830e4cb265e7e047aab2e79672a760a12712d2a263c9003509

Indexes

An index is an entity that gathers a set of documents with its own settings.
Learn more about indexes.

List Indexes

GET /indexes
Api key

List all indexes.

Query parameters

  • limit number

    Maximum number of results to return.

    Default value is 20.

  • offset number

    Number of results to skip.

    Default value is 0.

Responses

  • • 200 object

    Ok

    • results array[object] Required
    • limit integer Required

      Limit given for the query. If limit is not provided as a query parameter, this parameter displays the default limit value.

    • offset integer Required

      Offset given for the query. If offset is not provided as a query parameter, this parameter displays the default offset value.

    • total integer Required

      Total number of browsable results using offset/limit parameters for the given resource.

  • • 401 object

    Unauthorized

GET /indexes 
curl \
 -X GET https://example.meilisearch.com:7700/indexes \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200) 
{
  "results": [
    {
      "uid": "movies",
      "primaryKey": "movie_id",
      "createdAt": "2019-11-20T09:40:33.711324Z",
      "updatedAt": "2019-11-20T09:40:33.711324Z"
    }
  ],
  "limit": 1,
  "offset": 0,
  "total": 1
}
Response example (401) 
{
  "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"
}

Create Index

POST /indexes
Api key

Create an index.

Headers

  • Content-Type string Required

    Payload content-type

    Values are application/json.

Body Required

Responses

POST /indexes 
curl \
 -X POST https://example.meilisearch.com:7700/indexes \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"uid":"movies","primaryKey":"movie_id"}'
Request example 
# Headers
Content-Type: application/json

# Payload
{
  "uid": "movies",
  "primaryKey": "movie_id"
}
Response example (202) 
{
  "taskUid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "indexCreation",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z"
}
Response examples (400) 
{
  "message": "Index `:indexUid` already exists.",
  "code": "index_already_exists",
  "type": "invalid_request",
  "link": "https://docs.meilisearch.com/errors#index_already_exists"
}
{
  "message": "`:indexUid` is not a valid index uid. Index uid can be an integer or a string containing only alphanumeric characters, hyphens (-) and underscores (_).",
  "code": "invalid_index_uid",
  "type": "invalid_request",
  "link": "https://docs.meilisearch.com/errors#invalid_index_uid"
}
Response example (401) 
{
  "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"
}

Get Index

GET /indexes/{indexUid}
Api key

Get information about an index.

Responses

GET /indexes/{indexUid} 
curl \
 -X GET https://example.meilisearch.com:7700/indexes/{indexUid} \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200) 
{
  "uid": "movies",
  "primaryKey": "movie_id",
  "createdAt": "2019-11-20T09:40:33.711324Z",
  "updatedAt": "2019-11-20T09:40:33.711324Z"
}
Response example (401) 
{
  "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"
}

Delete Index

DELETE /indexes/{indexUid}
Api key

Delete an index.

Responses

DELETE /indexes/{indexUid} 
curl \
 -X DELETE https://example.meilisearch.com:7700/indexes/{indexUid} \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (202) 
{
  "taskUid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "indexDeletion",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z"
}
Response example (401) 
{
  "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"
}

Update Index

PATCH /indexes/{indexUid}
Api key

Update an index. Specify a primaryKey if it doesn't already exists yet.

Headers

  • Content-Type string Required

    Payload content-type

    Values are application/json.

Body Required

Responses

PATCH /indexes/{indexUid} 
curl \
 -X PATCH https://example.meilisearch.com:7700/indexes/{indexUid} \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"primaryKey":"string"}'
Request example 
# Headers
Content-Type: application/json

# Payload
{
  "primaryKey": "string"
}
Response example (202) 
{
  "taskUid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "indexUpdate",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z"
}
Response example (400) 
{
  "message": "Index `:indexUid` already has a primary key.",
  "code": "index_primary_key_already_exists",
  "type": "invalid_request",
  "link": "https://docs.meilisearch.com/errors#index_primary_key_already_exists"
}
Response example (401) 
{
  "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"
}

Swap Indexes

POST /swap-indexes
Api key

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.

Headers

  • Content-Type string Required

    Payload content-type

    Values are application/json.

Body

  • indexes array Required

    The two indexUids to swap in the given operation.

Responses

POST /swap-indexes 
curl \
 -X POST https://example.meilisearch.com:7700/swap-indexes \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '[{"indexes":["indexA","indexA_new"]},{"indexes":["indexB","indexB_new"]}]'
Request example 
# Headers
Content-Type: application/json

# Payload
[
  {
    "indexes": [
      "indexA",
      "indexA_new"
    ]
  },
  {
    "indexes": [
      "indexB",
      "indexB_new"
    ]
  }
]
Response example (202) 
{
  "taskUid": 0,
  "indexUid": null,
  "status": "enqueued",
  "type": "indexSwap",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z"
}
Response example (401) 
{
  "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"
}

Documents

Documents are objects composed of fields that can store any type of data.
Each field contains an attribute and its associated value.
Documents are stored inside indexes.
Learn more about documents.

Get Documents

GET /indexes/{indexUid}/documents
Api key

Get documents by batch.

Query parameters

  • limit number

    Maximum number of results to return.

    Default value is 20.

  • offset number

    Number of results to skip.

    Default value is 0.

  • fields string

    Comma-separated list of fields to display for an API resource. By default it contains all fields of an API resource.

    Default value is *.

Responses

  • • 200 object

    Ok

    • results array[object] Required
    • limit integer Required

      Limit given for the query. If limit is not provided as a query parameter, this parameter displays the default limit value.

    • offset integer Required

      Offset given for the query. If offset is not provided as a query parameter, this parameter displays the default offset value.

    • total integer Required

      Total number of browsable results using offset/limit parameters for the given resource.

  • • 401 object

    Unauthorized

  • • 404

    Not Found

GET /indexes/{indexUid}/documents 
curl \
 -X GET https://example.meilisearch.com:7700/indexes/{indexUid}/documents \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200) 
{
  "results": [
    {
      "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
    },
    {
      "id": 45881,
      "title": "The Bridge of San Luis Rey",
      "poster": "https://image.tmdb.org/t/p/w500/4X7quIcdkc24Cveg5XdpfRqxtYA.jpg",
      "overview": "The Bridge of San Luis Rey is American author Thornton Wilder's second novel, first published in 1927 to worldwide acclaim. It tells the story of several interrelated people who die in the collapse of an Inca rope-fiber suspension bridge in Peru, and the events that lead up to their being on the bridge.[ A friar who has witnessed the tragic accident then goes about inquiring into the lives of the victims, seeking some sort of cosmic answer to the question of why each had to die. The novel won the Pulitzer Prize in 1928.",
      "release_date": 1072915200
    }
  ],
  "limit": 20,
  "offset": 0,
  "total": 2
}
Response example (401) 
{
  "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"
}

Add or update documents

PUT /indexes/{indexUid}/documents
Api key

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

If you send an already existing document (same id) the old document will be only partially updated according to the fields of the new document. Thus, any fields not present in the new document are kept and remained unchanged.

To completely overwrite a document, see Add or replace documents route.

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

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

Headers

  • Content-Type string Required

    The content-type associated with the format to be indexed

    Values are application/json, text/csv, or application/x-ndjson.

Body Required

Responses

PUT /indexes/{indexUid}/documents 
curl \
 -X PUT https://example.meilisearch.com:7700/indexes/{indexUid}/documents \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '[{"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}]'
Request example 
# Headers
Content-Type: application/json

# Payload
[
  {
    "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
  }
]
Response example (202) 
{
  "taskUid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "documentAdditionOrUpdate",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z"
}
Response example (401) 
{
  "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"
}
Response example (413) 
{
  "message": "The provided payload reached the size limit.",
  "code": "payload_too_large",
  "type": "invalid_request",
  "link": "https://docs.meilisearch.com/errors#payload_too_large"
}

Add or replace documents

POST /indexes/{indexUid}/documents
Api key

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.

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

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

Headers

  • Content-Type string Required

    The content-type associated with the format to be indexed

    Values are application/json, text/csv, or application/x-ndjson.

Body Required

array array

Responses

POST /indexes/{indexUid}/documents 
curl \
 -X POST https://example.meilisearch.com:7700/indexes/{indexUid}/documents \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json"
Request example 
# Headers
Content-Type: application/json

# Payload
[]
Response example (202) 
{
  "taskUid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "documentAdditionOrUpdate",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z"
}
Response example (401) 
{
  "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"
}
Response example (413) 
{
  "message": "The provided payload reached the size limit.",
  "code": "payload_too_large",
  "type": "invalid_request",
  "link": "https://docs.meilisearch.com/errors#payload_too_large"
}

Delete all documents

DELETE /indexes/{indexUid}/documents
Api key

Delete all documents in the specified index.

Responses

DELETE /indexes/{indexUid}/documents 
curl \
 -X DELETE https://example.meilisearch.com:7700/indexes/{indexUid}/documents \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (202) 
{
  "taskUid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "documentDeletion",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z"
}
Response example (401) 
{
  "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"
}

Delete documents

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

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

Headers

  • Content-Type string Required

    Payload content-type

    Values are application/json.

Body Required

array[string | number] array[string | number]

An array of document ids to delete

Responses

POST /indexes/{indexUid}/documents/delete-batch 
curl \
 -X POST https://example.meilisearch.com:7700/indexes/{indexUid}/documents/delete-batch \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '[1,2,3,"a string id"]'
Request example 
# Headers
Content-Type: application/json

# Payload
[
  1,
  2,
  3,
  "a string id"
]
Response example (202) 
{
  "taskUid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "documentDeletion",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z"
}
Response example (401) 
{
  "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"
}

Get one document

GET /indexes/{indexUid}/documents/{documentId}
Api key

Get one document using its unique id.

Query parameters

  • fields string

    Comma-separated list of fields to display for an API resource. By default it contains all fields of an API resource.

    Default value is *.

Responses

GET /indexes/{indexUid}/documents/{documentId} 
curl \
 -X GET https://example.meilisearch.com:7700/indexes/{indexUid}/documents/{documentId} \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200) 
{
  "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
}
Response example (401) 
{
  "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"
}

Delete one document

DELETE /indexes/{indexUid}/documents/{documentId}
Api key

Delete one document based on its unique id.

Responses

DELETE /indexes/{indexUid}/documents/{documentId} 
curl \
 -X DELETE https://example.meilisearch.com:7700/indexes/{indexUid}/documents/{documentId} \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (202) 
{
  "taskUid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "documentDeletion",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z"
}
Response example (401) 
{
  "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"
}

Meilisearch exposes 2 routes to perform searches:

  • A POST route: this is the preferred route when using API authentication, as it allows preflight request caching and better performances.
  • A GET route: the usage of this route is discouraged, unless you have good reason to do otherwise (specific caching abilities for example). Other than the differences mentioned above, the two routes are strictly equivalent.

Search

GET /indexes/{indexUid}/search
Api key

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

This route should only be used when no API key is required. If an API key is required, use the POST route instead.

Query parameters

  • q string

    Query string.

    Default value is "".

  • attributesToRetrieve string

    Comma-separated list of attributes whose fields will be present in the returned documents. Defaults to the displayedAttributes list which contains by default all attributes found in the documents.

    Default value is *.

  • attributesToHighlight string

    Comma-separated list of attributes whose values will contain highlighted matching terms. Highlighted attributes are returned in _formatted response object.

  • highlightPreTag string

    Specify the tag to put before the highlighted query terms.

    Default value is <em>.

  • highlightPostTag string

    Specify the tag to put after the highlighted query terms.

    Default value is </em>.

  • attributesToCrop string

    Comma-separated list of attributes whose values have to be cropped. Cropped attributes are returned in _formatted response object.

  • cropMarker string

    Sets the crop marker to apply before and/or after cropped part selected within an attribute defined in attributesToCrop parameter.

    Default value is ….

  • cropLength integer

    Sets the total number of words to keep around the matched part of an attribute specified in the attributesToCrop parameter.

    Default value is 10.

  • facets string

    Comma-separated list of attributes whose fields will be distributed as a facet. If you have set up filterableAttributes, you can retrieve the count of matching terms for each facets.Learn more about facet distribution in the dedicated guide

  • filter

    Attribute(s) to filter on.

    Can be made of 3 syntaxes

    • Nested Array: ["something > 1", "genres=comedy", ["genres=horror", "title=batman"]]
    • String: something > 1 AND genres=comedy AND (genres=horror OR title=batman)
    • Mixed: ["something > 1 AND genres=comedy", "genres=horror OR title=batman"]

    _geoRadius({lat}, {lng}, {distance_in_meters}) built-in filter rule can be used to filter documents within a geo circle.

    Attribute(s) used in filter should be declared as filterable attributes. See Filtering and Faceted Search.

  • offset number

    Number of results to skip.

    Default value is 0.

  • sort string

    Fields on which you want to sort the results.

    Attribute(s) used in sort should be declared as sortable attributes. See Sorting.

    _geoPoint({lat}, {long}) built-in sort rule can be used to sort documents around a geo point.

  • limit number

    Maximum number of results to return.

    Default value is 20.

  • page number

    Sets the specific results page.

    Default value is 1.

  • hitsPerPage number

    Sets the number of results returned for a query. If hitsPerPage is not provided as a query parameter, this parameter is ignored.

    Default value is 20.

  • showMatchesPosition boolean

    Defines whether an _matchesPosition object that contains information about the matches should be returned or not.

    Default value is false.

  • matchingStrategy string

    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.

    Values are last or all. Default value is last.

Responses

GET /indexes/{indexUid}/search 
curl \
 -X GET https://example.meilisearch.com:7700/indexes/{indexUid}/search \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200) 
{
  "hits": [
    {
      "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,
      "_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
      },
      "_matchesPosition": {
        "overview": [
          {
            "start": 49,
            "length": 5
          },
          {
            "start": 155,
            "length": 5
          }
        ]
      }
    }
  ],
  "limit": 0,
  "offset": 0,
  "estimatedTotalHits": 0,
  "query": "string",
  "processingTimeMs": 0
}
Response example (401) 
{
  "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"
}

Search

POST /indexes/{indexUid}/search
Api key

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.

Headers

  • Content-Type string Required

    Payload content-type

    Values are application/json.

Body Required

  • q string

    Query string.

    Default value is "".

  • attributesToRetrieve array[string]

    Array of attributes whose fields will be present in the returned documents. Defaults to the displayedAttributes list which contains by default all attributes found in the documents.

    Default value is ["*"].

  • attributesToHighlight array[string]

    Array of attributes whose values will contain highlighted matching terms. Highlighted attributes are returned in _formatted response object.

    Default value is [].

  • highlightPreTag string

    Specify the tag to put before the highlighted query terms.

    Default value is <em>.

  • highlightPostTag string

    Specify the tag to put after the highlighted query terms.

    Default value is </em>.

  • attributesToCrop array[string]

    Array of attributes whose values have to be cropped. Cropped attributes are returned in _formatted response object.

    Default value is [].

  • cropMarker string

    Sets the crop marker to apply before and/or after cropped part selected within an attribute defined in attributesToCrop parameter.

    Default value is ….

  • cropLength number

    Sets the total number of words to keep for the cropped part of an attribute specified in the attributesToCrop parameter.

    Default value is 10.

  • showMatchesPosition boolean

    Defines whether an _matchesPosition object that contains information about the matches should be returned or not.

    Default value is false.

  • matchingStrategy string

    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.

    Default value is last.

  • filter array[string] | string | array[array | string]
    One of:
    array-1 array[string] string-2 string array-3 array[array | string]
    array-1 array[string]

    Attribute(s) to filter on.

    Can be made of 3 syntaxes

    • Nested Array: ["something > 1", "genres=comedy", ["genres=horror", "title=batman"]]
    • String: "something > 1 AND genres=comedy AND (genres=horror OR title=batman)"
    • Mixed: ["something > 1 AND genres=comedy", "genres=horror OR title=batman"]

    _geoRadius({lat}, {lng}, {distance_in_meters}) built-in filter rule can be used to filter documents within a geo circle.

    Attribute(s) used in filter should be declared as filterable attributes. See Filtering and Faceted Search.

    string-2 string

    Attribute(s) to filter on.

    Can be made of 3 syntaxes

    • Nested Array: ["something > 1", "genres=comedy", ["genres=horror", "title=batman"]]
    • String: "something > 1 AND genres=comedy AND (genres=horror OR title=batman)"
    • Mixed: ["something > 1 AND genres=comedy", "genres=horror OR title=batman"]

    _geoRadius({lat}, {lng}, {distance_in_meters}) built-in filter rule can be used to filter documents within a geo circle.

    Attribute(s) used in filter should be declared as filterable attributes. See Filtering and Faceted Search.

    array-3 array[array | string]

    Attribute(s) to filter on.

    Can be made of 3 syntaxes

    • Nested Array: ["something > 1", "genres=comedy", ["genres=horror", "title=batman"]]
    • String: "something > 1 AND genres=comedy AND (genres=horror OR title=batman)"
    • Mixed: ["something > 1 AND genres=comedy", "genres=horror OR title=batman"]

    _geoRadius({lat}, {lng}, {distance_in_meters}) built-in filter rule can be used to filter documents within a geo circle.

    Attribute(s) used in filter should be declared as filterable attributes. See Filtering and Faceted Search.

  • facets array[string]

    Array of attributes whose fields will be distributed as a facet. If you have set up filterableAttributes, you can retrieve the count of matching terms for each facets.Learn more about facet distribution in the dedicated guide

    Default value is [].

  • offset number

    Number of documents to skip.

    Default value is 0.

  • limit number

    Maximum number of documents returned.

    Default value is 20.

  • page number

    The specific search results page to fetch.

  • hitsPerPage number

    Number of returned results per page.

  • sort array[string]

    Fields on which you want to sort the results.

    Attribute(s) used in sort should be declared as sortable attributes. See Sorting.

    _geoPoint({lat}, {long}) built-in sort rule can be used to sort documents around a geo point.

  • Additional properties are NOT allowed

Responses

POST /indexes/{indexUid}/search 
curl \
 -X POST https://example.meilisearch.com:7700/indexes/{indexUid}/search \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"q":"Harry","offset":0,"limit":20,"filter":"(genres = Horror AND genres = Mystery) OR release_date \u003e 523242000","facets":["genres","author"],"attributesToRetrieve":["title","overview"],"attributesToCrop":["overview"],"cropLength":20,"attributesToHighlight":["overview"],"showMatchesPosition":true,"wordsMatchingStrategy":"all"}'
Request example 
# Headers
Content-Type: application/json

# Payload
{
  "q": "Harry",
  "offset": 0,
  "limit": 20,
  "filter": "(genres = Horror AND genres = Mystery) OR release_date > 523242000",
  "facets": [
    "genres",
    "author"
  ],
  "attributesToRetrieve": [
    "title",
    "overview"
  ],
  "attributesToCrop": [
    "overview"
  ],
  "cropLength": 20,
  "attributesToHighlight": [
    "overview"
  ],
  "showMatchesPosition": true,
  "wordsMatchingStrategy": "all"
}
Response example (200) 
{
  "hits": [
    {
      "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,
      "_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
      },
      "_matchesPosition": {
        "overview": [
          {
            "start": 49,
            "length": 5
          },
          {
            "start": 155,
            "length": 5
          }
        ]
      }
    }
  ],
  "limit": 0,
  "offset": 0,
  "estimatedTotalHits": 0,
  "query": "string",
  "processingTimeMs": 0
}
Response example (401) 
{
  "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"
}

Tasks

The tasks route gives information about the progress of the asynchronous operations.

Get all tasks

GET /tasks
Api key

Get all tasks

Query parameters

  • limit number

    Maximum number of results to return.

    Default value is 20.

  • from number

    Fetch the next set of results from the given uid.

  • uids 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 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 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 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 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 string

    Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued before the given date. Supports RFC 3339 date format.

  • afterEnqueuedAt string

    Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued after the given date. Supports RFC 3339 date format.

  • beforeStartedAt string

    Permits to filter tasks based on their startedAt time. Matches tasks started before the given date. Supports RFC 3339 date format.

  • afterStartedAt string

    Permits to filter tasks based on their startedAt time. Matches tasks started after the given date. Supports RFC 3339 date format.

  • beforeFinishedAt string

    Permits to filter tasks based on their finishedAt time. Matches tasks finished before the given date. Supports RFC 3339 date format.

  • afterFinishedAt string

    Permits to filter tasks based on their finishedAt time. Matches tasks finished after the given date. Supports RFC 3339 date format.

Responses

  • • 200 object

    OK

    • results array[object] Required
      • uid integer Required

        The unique sequential identifier of the task

      • indexUid string Required

        The unique identifier of the index where this task is operated

      • status string Required

        The status of the task

        Values are enqueued, processing, succeeded, or failed.

      • type string Required

        The type of the task

        Values are documentAdditionOrUpdate, documentDeletion, indexCreation, indexUpdate, indexDeletion, indexSwap, settingsUpdate, dumpCreation, taskCancelation, taskDeletion, or snapshotCreation.

      • canceledBy integer Required

        The uid of the task that performed the taskCancelation if the task has been canceled.

      • details object Required

        Details information of the task payload.

      • error object Required
      • duration string | null

        Total elasped time the engine was in processing state expressed as a ISO-8601 duration format. Default is set to null

      • enqueuedAt string Required

        An RFC 3339 format for date/time/duration.

      • startedAt string Required

        An RFC 3339 format for date/time/duration.

      • finishedAt string Required

        An RFC 3339 format for date/time/duration.

      • Additional properties are NOT allowed
    • limit integer Required

      Limit given for the query. If limit is not provided as a query parameter, this parameter displays the default limit value.

    • from integer Required

      The first task uid returned.

    • next integer Required

      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.

GET /tasks 
curl \
 -X GET https://example.meilisearch.com:7700/tasks \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200) 
{
  "results": [
    {
      "uid": 1,
      "indexUid": "movies",
      "status": "succeeded",
      "type": "documentAdditionOrUpdate",
      "canceledBy": null,
      "details": {
        "receivedDocuments": 79000,
        "indexedDocuments": 79000
      },
      "error": null,
      "duration": "PT1S",
      "enqueuedAt": "2021-01-01T09:39:00.000000Z",
      "startedAt": "2021-01-01T09:39:01.000000Z",
      "finishedAt": "2021-01-01T09:39:02.000000Z"
    },
    {
      "uid": 0,
      "indexUid": "movies_Review",
      "status": "failed",
      "type": "documentAdditionOrUpdate",
      "canceledBy": null,
      "details": {
        "receivedDocuments": 67493,
        "indexedDocuments": 0
      },
      "error": {
        "message": "Document does not have a `:primaryKey` attribute: `:documentRepresentation`.",
        "code": "missing_document_id",
        "type": "invalid_request",
        "link": "https://docs.meilisearch.com/errors#missing_document_id"
      },
      "duration": "PT5S",
      "enqueuedAt": "2021-01-01T09:38:00.000000Z",
      "startedAt": "2021-01-01T09:38:02.000000Z",
      "finishedAt": "2021-01-01T09:38:07.000000Z"
    }
  ],
  "limit": 2,
  "from": 1,
  "next": null
}

Delete tasks

DELETE /tasks
Api key

Delete finished tasks

Query parameters

  • uids 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 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 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 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 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 string

    Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued before the given date. Supports RFC 3339 date format.

  • afterEnqueuedAt string

    Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued after the given date. Supports RFC 3339 date format.

  • beforeStartedAt string

    Permits to filter tasks based on their startedAt time. Matches tasks started before the given date. Supports RFC 3339 date format.

  • afterStartedAt string

    Permits to filter tasks based on their startedAt time. Matches tasks started after the given date. Supports RFC 3339 date format.

  • beforeFinishedAt string

    Permits to filter tasks based on their finishedAt time. Matches tasks finished before the given date. Supports RFC 3339 date format.

  • afterFinishedAt string

    Permits to filter tasks based on their finishedAt time. Matches tasks finished after the given date. Supports RFC 3339 date format.

Responses

DELETE /tasks 
curl \
 -X DELETE https://example.meilisearch.com:7700/tasks \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (202) 
{
  "taskUid": 0,
  "indexUid": null,
  "status": "enqueued",
  "type": "taskDeletion",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z"
}
Response example (400) 
{
  "message": "string",
  "code": "string",
  "type": "string",
  "link": "string"
}

Get a task

GET /tasks/:taskUid
Api key

Get a task

Path parameters

  • taskUid integer Required

    The task identifier

Responses

  • • 200 object

    OK

    • uid integer Required

      The unique sequential identifier of the task

    • indexUid string Required

      The unique identifier of the index where this task is operated

    • status string Required

      The status of the task

      Values are enqueued, processing, succeeded, or failed.

    • type string Required

      The type of the task

      Values are documentAdditionOrUpdate, documentDeletion, indexCreation, indexUpdate, indexDeletion, indexSwap, settingsUpdate, dumpCreation, taskCancelation, taskDeletion, or snapshotCreation.

    • canceledBy integer Required

      The uid of the task that performed the taskCancelation if the task has been canceled.

    • details object Required

      Details information of the task payload.

    • error object Required
    • duration string | null

      Total elasped time the engine was in processing state expressed as a ISO-8601 duration format. Default is set to null

    • enqueuedAt string Required

      An RFC 3339 format for date/time/duration.

    • startedAt string Required

      An RFC 3339 format for date/time/duration.

    • finishedAt string Required

      An RFC 3339 format for date/time/duration.

    • Additional properties are NOT allowed
  • • 401 object

    Unauthorized

  • • 404 object

    Not Found

GET /tasks/:taskUid 
curl \
 -X GET https://example.meilisearch.com:7700/tasks/:taskUid \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200) 
{
  "uid": 1,
  "indexUid": "movies",
  "status": "succeeded",
  "type": "documentAdditionOrUpdate",
  "canceledBy": null,
  "details": {
    "receivedDocuments": 79000,
    "indexedDocuments": 79000
  },
  "error": null,
  "duration": "PT1S",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z",
  "startedAt": "2021-01-01T09:39:01.000000Z",
  "finishedAt": "2021-01-01T09:39:02.000000Z"
}
Response example (401) 
{
  "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"
}
Response example (404) 
{
  "message": "Task :taskUid not found.",
  "code": "task_not_found",
  "type": "invalid_request",
  "link": "https://docs.meilisearch.com/errors/#task_not_found"
}

Cancel tasks

POST /tasks/cancel
Api key

Cancel enqueued and/or processing tasks

Query parameters

  • uids 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 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 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 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 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 string

    Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued before the given date. Supports RFC 3339 date format.

  • afterEnqueuedAt string

    Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued after the given date. Supports RFC 3339 date format.

  • beforeStartedAt string

    Permits to filter tasks based on their startedAt time. Matches tasks started before the given date. Supports RFC 3339 date format.

  • afterStartedAt string

    Permits to filter tasks based on their startedAt time. Matches tasks started after the given date. Supports RFC 3339 date format.

  • beforeFinishedAt string

    Permits to filter tasks based on their finishedAt time. Matches tasks finished before the given date. Supports RFC 3339 date format.

  • afterFinishedAt string

    Permits to filter tasks based on their finishedAt time. Matches tasks finished after the given date. Supports RFC 3339 date format.

Responses

POST /tasks/cancel 
curl \
 -X POST https://example.meilisearch.com:7700/tasks/cancel \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (202) 
{
  "taskUid": 0,
  "indexUid": null,
  "status": "enqueued",
  "type": "taskCancelation",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z"
}
Response example (400) 
{
  "message": "string",
  "code": "string",
  "type": "string",
  "link": "string"
}
Response example (401) 
{
  "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"
}

Keys

Manage API keys for a Meilisearch instance. Each key has a given set of permissions.
You must have the master key or the default admin key to access the keys route.
More information about the keys and their rights.

Get API Keys

GET /keys
Api key

Get API Keys

Query parameters

  • limit number

    Maximum number of results to return.

    Default value is 20.

  • offset number

    Number of results to skip.

    Default value is 0.

Responses

  • • 200 object

    Ok

    • results array[object] Required
      • uid string

        A uuid v4 to identify the API Key. If not specified, it's generated by Meilisearch.

      • key string

        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.

      • actions array[string] Required

        A list of actions permitted for the key. ["*"] for all actions.

        Values are 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, dumps.create, version, keys.get, keys.create, keys.update, or keys.delete.

      • indexes array[string] Required

        A list of accesible indexes permitted for the key. ["*"] for all indexes.

      • name string | null

        A human-readable name for the key. null if empty.

      • description string | null

        A description for the key. null if empty.

      • expiresAt string | null Required

        Represent the expiration date and time as RFC 3339 format. null equals to no expiration time.

      • createdAt string

        Represent the date and time as RFC 3339 format when the API key has been created. Generated by Meilisearch.

      • updatedAt string | null

        Represent the date and time as RFC 3339 format when the API key has been updated. Generated by Meilisearch.

    • limit integer Required

      Limit given for the query. If limit is not provided as a query parameter, this parameter displays the default limit value.

    • offset integer Required

      Offset given for the query. If offset is not provided as a query parameter, this parameter displays the default offset value.

    • total integer Required

      Total number of browsable results using offset/limit parameters for the given resource.

  • • 401 object

    Unauthorized

GET /keys 
curl \
 -X GET https://example.meilisearch.com:7700/keys \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200) 
{
  "results": [
    {
      "uid": "01b4bc42-eb33-4041-b481-254d00cce834",
      "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
      "name": "An API Key",
      "description": null,
      "actions": [
        "documents.add"
      ],
      "indexes": [
        "movies"
      ],
      "expiresAt": "2022-11-12T10:00:00Z",
      "createdAt": "2021-11-12T10:00:00Z",
      "updatedAt": "2021-11-12T10:00:00Z"
    }
  ],
  "limit": 20,
  "offset": 0,
  "total": 1
}
Response example (401) 
{
  "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"
}

Create an API Key

POST /keys
Api key

Headers

  • Content-Type string Required

    Payload content-type

    Values are application/json.

Body

  • uid string

    A uuid v4 to identify the API Key. If not specified, it's generated by Meilisearch.

  • key string

    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.

  • actions array[string] Required

    A list of actions permitted for the key. ["*"] for all actions.

    Values are 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, dumps.create, version, keys.get, keys.create, keys.update, or keys.delete.

  • indexes array[string] Required

    A list of accesible indexes permitted for the key. ["*"] for all indexes.

  • name string | null

    A human-readable name for the key. null if empty.

  • description string | null

    A description for the key. null if empty.

  • expiresAt string | null Required

    Represent the expiration date and time as RFC 3339 format. null equals to no expiration time.

  • createdAt string

    Represent the date and time as RFC 3339 format when the API key has been created. Generated by Meilisearch.

  • updatedAt string | null

    Represent the date and time as RFC 3339 format when the API key has been updated. Generated by Meilisearch.

Responses

  • • 200 object

    OK

    • uid string

      A uuid v4 to identify the API Key. If not specified, it's generated by Meilisearch.

    • key string

      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.

    • actions array[string] Required

      A list of actions permitted for the key. ["*"] for all actions.

      Values are 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, dumps.create, version, keys.get, keys.create, keys.update, or keys.delete.

    • indexes array[string] Required

      A list of accesible indexes permitted for the key. ["*"] for all indexes.

    • name string | null

      A human-readable name for the key. null if empty.

    • description string | null

      A description for the key. null if empty.

    • expiresAt string | null Required

      Represent the expiration date and time as RFC 3339 format. null equals to no expiration time.

    • createdAt string

      Represent the date and time as RFC 3339 format when the API key has been created. Generated by Meilisearch.

    • updatedAt string | null

      Represent the date and time as RFC 3339 format when the API key has been updated. Generated by Meilisearch.

POST /keys 
curl \
 -X POST https://example.meilisearch.com:7700/keys \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"name":"Indexing Products API key","actions":["documents.add"],"indexes":["products"],"expiresAt":"2021-11-13T00:00:00Z"}'
Request example 
# Headers
Content-Type: application/json

# Payload
{
  "name": "Indexing Products API key",
  "actions": [
    "documents.add"
  ],
  "indexes": [
    "products"
  ],
  "expiresAt": "2021-11-13T00:00:00Z"
}
Response example (200) 
{
  "uid": "01b4bc42-eb33-4041-b481-254d00cce834",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "name": "Indexing Products API key",
  "description": null,
  "actions": [
    "documents.add"
  ],
  "indexes": [
    "products"
  ],
  "expiresAt": "2021-11-13T00:00:00Z",
  "createdAt": "2021-11-12T10:00:00Z",
  "updatedAt": "2021-11-12T10:00:00Z"
}

Get an API key from its uid or key field.

GET /keys/{uid_or_key}
Api key

Get an API Key

Path parameters

  • uidOrKey string Required

    The uid or the key field value of the API Key.

Responses

  • • 200 object

    OK

    • uid string

      A uuid v4 to identify the API Key. If not specified, it's generated by Meilisearch.

    • key string

      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.

    • actions array[string] Required

      A list of actions permitted for the key. ["*"] for all actions.

      Values are 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, dumps.create, version, keys.get, keys.create, keys.update, or keys.delete.

    • indexes array[string] Required

      A list of accesible indexes permitted for the key. ["*"] for all indexes.

    • name string | null

      A human-readable name for the key. null if empty.

    • description string | null

      A description for the key. null if empty.

    • expiresAt string | null Required

      Represent the expiration date and time as RFC 3339 format. null equals to no expiration time.

    • createdAt string

      Represent the date and time as RFC 3339 format when the API key has been created. Generated by Meilisearch.

    • updatedAt string | null

      Represent the date and time as RFC 3339 format when the API key has been updated. Generated by Meilisearch.

GET /keys/{uid_or_key} 
curl \
 -X GET https://example.meilisearch.com:7700/keys/{uid_or_key} \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200) 
{
  "uid": "01b4bc42-eb33-4041-b481-254d00cce834",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "name": "Indexing Products API key",
  "description": null,
  "actions": [
    "documents.add"
  ],
  "indexes": [
    "products"
  ],
  "expiresAt": "2021-11-13T00:00:00Z",
  "createdAt": "2021-11-12T10:00:00Z",
  "updatedAt": "2021-11-12T10:00:00Z"
}

Delete an API key specified by its uid or key field.

DELETE /keys/{uid_or_key}
Api key

Responses

DELETE /keys/{uid_or_key} 
curl \
 -X DELETE https://example.meilisearch.com:7700/keys/{uid_or_key} \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Update an API key specified by its uid or key field.

PATCH /keys/{uid_or_key}
Api key

Update an API Key

Headers

  • Content-Type string Required

    Payload content-type

    Values are application/json.

Body

Responses

  • • 200 object

    OK

    • uid string

      A uuid v4 to identify the API Key. If not specified, it's generated by Meilisearch.

    • key string

      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.

    • actions array[string] Required

      A list of actions permitted for the key. ["*"] for all actions.

      Values are 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, dumps.create, version, keys.get, keys.create, keys.update, or keys.delete.

    • indexes array[string] Required

      A list of accesible indexes permitted for the key. ["*"] for all indexes.

    • name string | null

      A human-readable name for the key. null if empty.

    • description string | null

      A description for the key. null if empty.

    • expiresAt string | null Required

      Represent the expiration date and time as RFC 3339 format. null equals to no expiration time.

    • createdAt string

      Represent the date and time as RFC 3339 format when the API key has been created. Generated by Meilisearch.

    • updatedAt string | null

      Represent the date and time as RFC 3339 format when the API key has been updated. Generated by Meilisearch.

PATCH /keys/{uid_or_key} 
curl \
 -X PATCH https://example.meilisearch.com:7700/keys/{uid_or_key} \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"description":"Indexing Products API key"}'
Request example 
# Headers
Content-Type: application/json

# Payload
{
  "description": "Indexing Products API key"
}
Response example (200) 
{
  "uid": "01b4bc42-eb33-4041-b481-254d00cce834",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "name": "Indexing Products API key",
  "description": null,
  "actions": [
    "documents.add"
  ],
  "indexes": [
    "products"
  ],
  "expiresAt": "2021-11-13T00:00:00Z",
  "createdAt": "2021-11-12T10:00:00Z",
  "updatedAt": "2021-11-12T15:00:00Z"
}

Settings

Settings is a list of all the customization possible for an index.
It is possible to update all the settings in one go or individually with the dedicated routes. Updates in the settings route are partial. This means that any parameters not provided in the body will be left unchanged.
Updating the settings means overwriting the default settings of Meilisearch. You can reset to default values using the DELETE routes.

Get settings

GET /indexes/{indexUid}/settings
Api key

Get the settings of an index.

Learn more about the settings.

Responses

  • • 200 object

    Ok

    • rankingRules array[string] Required

      List of ranking rules sorted by order of importance. The order is customizable.

      A list of ordered built-in ranking rules.

    • distinctAttribute string | null Required

      Search returns documents with distinct (different) values of the given field.

    • searchableAttributes array[string] Required

      Fields in which to search for matching query words sorted by order of importance.

    • displayedAttributes array[string] Required

      Fields displayed in the returned documents.

    • stopWords array[string] Required

      List of words ignored when present in search queries.

    • synonyms object Required

      List of associated words treated similarly. A word associated to an array of word as synonyms.

    • filterableAttributes array[string] Required

      Attributes to use for faceting and filtering. See Filtering and Faceted Search.

    • sortableAttributes array[string] Required

      List of attributes to sort on at search.

    • typoTolerance object Required

      Customize typo tolerance feature.

      • enabled boolean

        Enable the typo tolerance feature.

        Default value is true.

      • disableOnAttributes array[string]

        Disable the typo tolerance feature on the specified attributes.

        Default value is [].

      • disableOnWords array[string]

        Disable the typo tolerance feature for a set of query terms given for a search query.

        Default value is [].

      • minWordSizeForTypos object
        • oneTypo integer

          Customize the minimum size for a word to tolerate 1 typo.

          Default value is 5.

        • twoTypos integer

          Customize the minimum size for a word to tolerate 2 typos.

          Default value is 9.

    • pagination object Required

      Customize pagination settings

      • maxTotalHits integer

        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 1001st result for a search query.

        Default value is 1000.

    • faceting object Required

      Customize faceting settings

      • maxValuesPerFacet integer

        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.

        Default value is 100.

  • • 401 object

    Unauthorized

  • • 404

    Not Found

GET /indexes/{indexUid}/settings 
curl \
 -X GET https://example.meilisearch.com:7700/indexes/{indexUid}/settings \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200) 
{
  "rankingRules": [
    "words",
    "typo",
    "proximity",
    "attribute",
    "sort",
    "exactness",
    "release_date:asc"
  ],
  "distinctAttribute": "ean13",
  "searchableAttributes": [
    "title",
    "description",
    "genre"
  ],
  "displayedAttributes": [
    "title",
    "description",
    "genre",
    "release_date"
  ],
  "stopWords": [
    "of",
    "the",
    "to"
  ],
  "synonyms": {
    "wolverine": [
      "xmen",
      "logan"
    ],
    "logan": [
      "wolverine",
      "xmen"
    ],
    "wow": [
      "world of warcraft"
    ]
  },
  "filterableAttributes": [
    "genres",
    "director"
  ],
  "sortableAttributes": [
    "price",
    "author",
    "title"
  ],
  "typoTolerance": {
    "enabled": true,
    "disableOnAttributes": [
      "author",
      "price"
    ],
    "disableOnWords": [
      "Tolkien"
    ],
    "minWordSizeForTypos": {
      "oneTypo": 4,
      "twoTypos": 8
    }
  },
  "pagination": {
    "maxTotalHits": 1000
  },
  "faceting": {
    "maxValuesPerFacet": 100
  }
}
Response example (401) 
{
  "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"
}

Reset settings

DELETE /indexes/{indexUid}/settings
Api key

Reset the settings of an index.

All settings will be reset to their default value.

Responses

DELETE /indexes/{indexUid}/settings 
curl \
 -X DELETE https://example.meilisearch.com:7700/indexes/{indexUid}/settings \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (202) 
{
  "taskUid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z"
}
Response example (401) 
{
  "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"
}

Update settings

PATCH /indexes/{indexUid}/settings
Api key

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.

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

Headers

  • Content-Type string Required

    Payload content-type

    Values are application/json.

Body Required

  • synonyms object

    List of associated words treated similarly. A word associated to an array of word as synonyms.

  • stopWords array[string]

    List of words ignored when present in search queries.

  • rankingRules array[string]

    List of ranking rules sorted by order of importance. The order is customizable.

    A list of ordered built-in ranking rules.

  • distinctAttribute string | null

    Search returns documents with distinct (different) values of the given field.

  • searchableAttributes array[string]

    Fields in which to search for matching query words sorted by order of importance.

  • displayedAttributes array[string]

    Fields displayed in the returned documents.

  • filterableAttributes array[string]

    Attributes to use for faceting and filtering. See Filtering and Faceted Search.

  • sortableAttributes array[string]

    List of attributes to sort on at search.

  • typoTolerance object

    Customize typo tolerance feature.

    • enabled boolean

      Enable the typo tolerance feature.

      Default value is true.

    • disableOnAttributes array[string]

      Disable the typo tolerance feature on the specified attributes.

      Default value is [].

    • disableOnWords array[string]

      Disable the typo tolerance feature for a set of query terms given for a search query.

      Default value is [].

    • minWordSizeForTypos object
      • oneTypo integer

        Customize the minimum size for a word to tolerate 1 typo.

        Default value is 5.

      • twoTypos integer

        Customize the minimum size for a word to tolerate 2 typos.

        Default value is 9.

  • pagination object

    Customize pagination settings

    • maxTotalHits integer

      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 1001st result for a search query.

      Default value is 1000.

  • faceting object

    Customize faceting settings

    • maxValuesPerFacet integer

      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.

      Default value is 100.

  • Additional properties are NOT allowed

Responses

PATCH /indexes/{indexUid}/settings 
curl \
 -X PATCH https://example.meilisearch.com:7700/indexes/{indexUid}/settings \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"synonyms":{"wolverine":["xmen","logan"],"logan":["wolverine","xmen"],"wow":["world of warcraft"]},"stopWords":["of","the","to"],"rankingRules":["words","typo","proximity","attribute","sort","exactness","release_date:asc"],"distinctAttribute":"ean13","searchableAttributes":["title","description","genre"],"displayedAttributes":["title","description","genre","release_date"],"filterableAttributes":[],"sortableAttributes":null,"typoTolerance":{"enabled":false,"disableOnAttributes":["title","author"],"disableOnWords":["Tolkien"],"minWordSizeForTypos":{"oneTypo":4,"twoTypos":8}},"pagination":{"maxTotalHits":1000},"faceting":{"maxValuesPerFacet":100}}'
Request example 
# Headers
Content-Type: application/json

# Payload
{
  "synonyms": {
    "wolverine": [
      "xmen",
      "logan"
    ],
    "logan": [
      "wolverine",
      "xmen"
    ],
    "wow": [
      "world of warcraft"
    ]
  },
  "stopWords": [
    "of",
    "the",
    "to"
  ],
  "rankingRules": [
    "words",
    "typo",
    "proximity",
    "attribute",
    "sort",
    "exactness",
    "release_date:asc"
  ],
  "distinctAttribute": "ean13",
  "searchableAttributes": [
    "title",
    "description",
    "genre"
  ],
  "displayedAttributes": [
    "title",
    "description",
    "genre",
    "release_date"
  ],
  "filterableAttributes": [],
  "sortableAttributes": null,
  "typoTolerance": {
    "enabled": false,
    "disableOnAttributes": [
      "title",
      "author"
    ],
    "disableOnWords": [
      "Tolkien"
    ],
    "minWordSizeForTypos": {
      "oneTypo": 4,
      "twoTypos": 8
    }
  },
  "pagination": {
    "maxTotalHits": 1000
  },
  "faceting": {
    "maxValuesPerFacet": 100
  }
}
Response example (202) 
{
  "taskUid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z"
}
Response example (401) 
{
  "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"
}

Get synonyms

GET /indexes/{indexUid}/settings/synonyms
Api key

Get the list of synonyms of an index.

Responses

  • • 200 object

    Ok

    List of associated words treated similarly. A word associated to an array of word as synonyms.

  • • 401 object

    Unauthorized

  • • 404

    Not Found

GET /indexes/{indexUid}/settings/synonyms 
curl \
 -X GET https://example.meilisearch.com:7700/indexes/{indexUid}/settings/synonyms \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200) 
{
  "wolverine": [
    "xmen",
    "logan"
  ],
  "logan": [
    "wolverine",
    "xmen"
  ],
  "wow": [
    "world of warcraft"
  ]
}
Response example (401) 
{
  "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"
}

Update synonyms

PUT /indexes/{indexUid}/settings/synonyms
Api key

Update the list of synonyms of an index. Synonyms are normalized.

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

Headers

  • Content-Type string Required

    Payload content-type

    Values are application/json.

Body Required

object object

List of associated words treated similarly. A word associated to an array of word as synonyms.

Responses

PUT /indexes/{indexUid}/settings/synonyms 
curl \
 -X PUT https://example.meilisearch.com:7700/indexes/{indexUid}/settings/synonyms \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"wolverine":["xmen","logan"],"logan":["wolverine","xmen"],"wow":["world of warcraft"]}'
Request example 
# Headers
Content-Type: application/json

# Payload
{
  "wolverine": [
    "xmen",
    "logan"
  ],
  "logan": [
    "wolverine",
    "xmen"
  ],
  "wow": [
    "world of warcraft"
  ]
}
Response example (202) 
{
  "taskUid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z"
}
Response example (401) 
{
  "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"
}

Reset synonyms

DELETE /indexes/{indexUid}/settings/synonyms
Api key

Reset the list of synonyms of an index to its default value ({}).

Responses

DELETE /indexes/{indexUid}/settings/synonyms 
curl \
 -X DELETE https://example.meilisearch.com:7700/indexes/{indexUid}/settings/synonyms \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (202) 
{
  "taskUid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z"
}
Response example (401) 
{
  "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"
}

Get sortable attributes

GET /indexes/{indexUid}/settings/sortable-attributes
Api key

Get the list of sortableAttributes of an index.

Responses

GET /indexes/{indexUid}/settings/sortable-attributes 
curl \
 -X GET https://example.meilisearch.com:7700/indexes/{indexUid}/settings/sortable-attributes \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200) 
[
  "price",
  "author",
  "title"
]
Response example (401) 
{
  "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"
}

Update sortable attributes

PUT /indexes/{indexUid}/settings/sortable-attributes
Api key

Update the list of sortableAttributes of an index.

In order to enable sorting capabilities on geographic data, the _geo field must be added as a sortableAttribute.

Headers

  • Content-Type string Required

    Payload content-type

    Values are application/json.

Body Required

array[string] array[string]

List of attributes to sort on at search.

Responses

PUT /indexes/{indexUid}/settings/sortable-attributes 
curl \
 -X PUT https://example.meilisearch.com:7700/indexes/{indexUid}/settings/sortable-attributes \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '["price","author","title"]'
Request example 
# Headers
Content-Type: application/json

# Payload
[
  "price",
  "author",
  "title"
]
Response example (202) 
{
  "taskUid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-01-01T09:39:00.000000Z"
}
Response example (401) 
{
  "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"
}

Reset sortable attributes

DELETE /indexes/{indexUid}/settings/sortable-attributes
Api key

Reset the list of sortableAttributes of an index to its default value ([]).

Responses