Search documents, configure and manage the Meilisearch engine.

This is the documentation for version 0.25.0 of the API. Last update on Jan 26, 2022.

This API is provided under license MIT.

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

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


List Indexes

List all indexes.

Responses
  • 200 array[object]

    Ok

    • uid Required / string

      Unique identifier for the index

    • name Required / string

      Name of the index

    • Custom primaryKey for documents

    • createdAt Required / string

      An ISO-8601 format for date/time/duration.

    • updatedAt Required / string

      An ISO-8601 format for date/time/duration.

  • 401 object

    Unauthorized

    • message Required / string
    • code Required / string
    • type Required / string
GET /indexes
curl \
 -X GET https://example.meilisearch.com:7700/indexes \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
[
  {
    "uid": "movies",
    "name": "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"
}

Create Index

Create an index.

Headers
  • Content-Type Required / string

    Payload content-type

    Values are application/json.

Body
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 (201)
{
  "uid": "movies",
  "name": "movies",
  "primaryKey": "movie_id",
  "createdAt": "2019-11-20T09:40:33.711324Z",
  "updatedAt": "2019-11-20T09:40:33.711324Z"
}
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 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",
  "name": "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"
}

Update Index

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

Headers
  • Content-Type Required / string

    Payload content-type

    Values are application/json.

Responses
PUT /indexes/{indexUid}
curl \
 -X PUT 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 (200)
{
  "uid": "movies",
  "name": "movies",
  "primaryKey": "movie_id",
  "createdAt": "2019-11-20T09:40:33.711324Z",
  "updatedAt": "2019-11-20T09:40:33.711324Z"
}
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"
}

Delete Index

Delete an index.

Responses
  • 204

    No Content

  • 401 object

    Unauthorized

    • message Required / string
    • code Required / string
    • type Required / string
  • 404

    Not Found

DELETE /indexes/{indexUid}
curl \
 -X DELETE https://example.meilisearch.com:7700/indexes/{indexUid} \
 -H "Authorization: Bearer $ACCESS_TOKEN"
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"
}

Query parameters
  • limit number

    Maximum number of documents to return.

    Default value is 20.

  • offset number

    Number of documents to skip.

    Default value is 0.

  • attributesToRetrieve array[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 *.

Responses
GET /indexes/{indexUid}/documents
curl \
 -X GET https://example.meilisearch.com:7700/indexes/{indexUid}/documents \
 -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": "1993-01-01"
  }
]
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

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 Required / string

    The content-type associated with the format to be indexed

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

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":"1993-01-01"}]'
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": "1993-01-01"
  }
]
Response example (202)
{
  "uid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "enqueuedAt": "2021-07-19T14:31:16.920473Z"
}
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

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 Required / string

    The content-type associated with the format to be indexed

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

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"
Response example (202)
{
  "uid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "enqueuedAt": "2021-07-19T14:31:16.920473Z"
}
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 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)
{
  "uid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "enqueuedAt": "2021-07-19T14:31:16.920473Z"
}
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

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

Headers
  • Content-Type Required / string

    Payload content-type

    Values are application/json.

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)
{
  "uid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "enqueuedAt": "2021-07-19T14:31:16.920473Z"
}
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 one document using its unique id.

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": "1993-01-01"
}
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 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)
{
  "uid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "enqueuedAt": "2021-07-19T14:31:16.920473Z"
}
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

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 Required / string

    Payload content-type

    Values are application/json.

Body
  • 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 [].

  • attributesToCrop array[string]

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

    Default value is [].

  • cropLength number

    Length used to crop field values.

    Default value is 200.

  • matches boolean

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

  • 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.

  • facetsDistribution 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.

  • 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.

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","facetsDistribution":["genres","author"],"attributesToRetrieve":["title","overview"],"attributesToCrop":["overview"],"cropLength":20,"attributesToHighlight":["overview"],"matches":true}'
Request example
# Headers
Content-Type: application/json

# Payload
{
  "q": "Harry",
  "offset": 0,
  "limit": 20,
  "filter": "(genres = Horror AND genres = Mystery) OR release_date > 523242000",
  "facetsDistribution": [
    "genres",
    "author"
  ],
  "attributesToRetrieve": [
    "title",
    "overview"
  ],
  "attributesToCrop": [
    "overview"
  ],
  "cropLength": 20,
  "attributesToHighlight": [
    "overview"
  ],
  "matches": true
}
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": "1993-01-01",
      "_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": "1993-01-01"
      },
      "_matchesInfo": {
        "overview": [
          {
            "start": 49,
            "length": 5
          },
          {
            "start": 155,
            "length": 5
          }
        ]
      }
    }
  ],
  "limit": 0,
  "offset": 0,
  "nbHits": 0,
  "query": "string",
  "exhaustiveNbHits": true,
  "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"
}

Responses
  • 200 object

    Ok

    • results array[object]
      • uid Required / integer

        The unique sequential identifier of the task

      • indexUid Required / string

        The unique identifier of the index where this task is operated

      • status Required / string

        The status of the task

        Values are enqueued, processing, succeeded, or failed.

      • type Required / string

        The type of the task

        Values are documentAddition, documentPartial, documentDeletion, indexCreation, indexUpdate, indexDeletion, settingsUpdate, or clearAll.

      • details object

        Details information of the task payload.

      • error object
        • message Required / string
        • code Required / string
        • type Required / string
      • duration string

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

      • enqueuedAt Required / string

        An ISO-8601 format for date/time/duration.

      • startedAt Required / string

        An ISO-8601 format for date/time/duration.

      • finishedAt Required / string

        An ISO-8601 format for date/time/duration.

  • 401 object

    Unauthorized

    • message Required / string
    • code Required / string
    • type Required / string
  • 404

    Not Found

GET /indexes/{indexUid}/tasks
curl \
 -X GET https://example.meilisearch.com:7700/indexes/{indexUid}/tasks \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "results": [
    {
      "uid": 1,
      "indexUid": "movies",
      "status": "succeeded",
      "type": "documentAddition",
      "details": {
        "receivedDocuments": 79000,
        "indexedDocuments": 79000
      },
      "duration": "PT2S",
      "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",
      "status": "failed",
      "type": "documentAddition",
      "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"
    }
  ]
}
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"
}
Responses
  • 200 object

    Ok

    • uid Required / integer

      The unique sequential identifier of the task

    • indexUid Required / string

      The unique identifier of the index where this task is operated

    • status Required / string

      The status of the task

      Values are enqueued, processing, succeeded, or failed.

    • type Required / string

      The type of the task

      Values are documentAddition, documentPartial, documentDeletion, indexCreation, indexUpdate, indexDeletion, settingsUpdate, or clearAll.

    • details object

      Details information of the task payload.

    • error object
      • message Required / string
      • code Required / string
      • type Required / string
    • duration string

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

    • enqueuedAt Required / string

      An ISO-8601 format for date/time/duration.

    • startedAt Required / string

      An ISO-8601 format for date/time/duration.

    • finishedAt Required / string

      An ISO-8601 format for date/time/duration.

  • 401 object

    Unauthorized

    • message Required / string
    • code Required / string
    • type Required / string
  • 404

    Not Found

GET /indexes/{indexUid}/tasks/{taskUid}
curl \
 -X GET https://example.meilisearch.com:7700/indexes/{indexUid}/tasks/{taskUid} \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "uid": 1,
  "indexUid": "movies",
  "status": "succeeded",
  "type": "documentAddition",
  "details": {
    "receivedDocuments": 79000,
    "indexedDocuments": 79000
  },
  "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"
}
Responses
  • 200 object

    OK

    • results array[object]
      • uid Required / integer

        The unique sequential identifier of the task

      • indexUid Required / string

        The unique identifier of the index where this task is operated

      • status Required / string

        The status of the task

        Values are enqueued, processing, succeeded, or failed.

      • type Required / string

        The type of the task

        Values are documentAddition, documentPartial, documentDeletion, indexCreation, indexUpdate, indexDeletion, settingsUpdate, or clearAll.

      • details object

        Details information of the task payload.

      • error object
        • message Required / string
        • code Required / string
        • type Required / string
      • duration string

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

      • enqueuedAt Required / string

        An ISO-8601 format for date/time/duration.

      • startedAt Required / string

        An ISO-8601 format for date/time/duration.

      • finishedAt Required / string

        An ISO-8601 format for date/time/duration.

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": "documentAddition",
      "details": {
        "receivedDocuments": 79000,
        "indexedDocuments": 79000
      },
      "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": "documentAddition",
      "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"
    }
  ]
}
Responses
  • 200 object

    OK

    • uid Required / integer

      The unique sequential identifier of the task

    • indexUid Required / string

      The unique identifier of the index where this task is operated

    • status Required / string

      The status of the task

      Values are enqueued, processing, succeeded, or failed.

    • type Required / string

      The type of the task

      Values are documentAddition, documentPartial, documentDeletion, indexCreation, indexUpdate, indexDeletion, settingsUpdate, or clearAll.

    • details object

      Details information of the task payload.

    • error object
      • message Required / string
      • code Required / string
      • type Required / string
    • duration string

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

    • enqueuedAt Required / string

      An ISO-8601 format for date/time/duration.

    • startedAt Required / string

      An ISO-8601 format for date/time/duration.

    • finishedAt Required / string

      An ISO-8601 format for date/time/duration.

  • 401 object

    Unauthorized

    • message Required / string
    • code Required / string
    • type Required / string
  • 404 object

    Not Found

    • message Required / string
    • code Required / string
    • type Required / string
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": "documentAddition",
  "details": {
    "receivedDocuments": 79000,
    "indexedDocuments": 79000
  },
  "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"
}

Get API Keys

Get API Keys

Responses
  • 200 object

    Ok

    • results array[object]
      • key string

        The generated key. Generated by Meilisearch.

      • actions Required / array[string]

        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, tasks.get, settings.get, settings.update, stats.get, dumps.create, dumps.get, or version.

      • indexes Required / array[string]

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

      • A description for the key. null if empty.

      • expiresAt Required /

        Represent the expiration date and time as ISO-8601 format. null equals to no expiration time.

      • createdAt string

        Represent the date and time as ISO-8601 format when the API key has been created. Generated by Meilisearch.

      • Represent the date and time as ISO-8601 format when the API key has been updated. Generated by Meilisearch.

  • 401 object

    Unauthorized

    • message Required / string
    • code Required / string
    • type Required / string
GET /keys
curl \
 -X GET https://example.meilisearch.com:7700/keys \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "results": [
    {
      "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
      "actions": [
        "documents.add"
      ],
      "indexes": [
        "movies"
      ],
      "description": "An API Key",
      "expiresAt": "2022-11-12T10:00:00Z",
      "createdAt": "2021-11-12T10:00:00Z",
      "updatedAt": "2021-11-12T10:00:00Z"
    }
  ]
}
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 an API key

Get an API Key

Responses
  • 200 object

    OK

    • key string

      The generated key. Generated by Meilisearch.

    • actions Required / array[string]

      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, tasks.get, settings.get, settings.update, stats.get, dumps.create, dumps.get, or version.

    • indexes Required / array[string]

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

    • A description for the key. null if empty.

    • expiresAt Required /

      Represent the expiration date and time as ISO-8601 format. null equals to no expiration time.

    • createdAt string

      Represent the date and time as ISO-8601 format when the API key has been created. Generated by Meilisearch.

    • Represent the date and time as ISO-8601 format when the API key has been updated. Generated by Meilisearch.

GET /keys/{key}
curl \
 -X GET https://example.meilisearch.com:7700/keys/{key} \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "description": "Indexing Products API key",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "actions": [
    "documents.add"
  ],
  "indexes": [
    "products"
  ],
  "expiresAt": "2021-11-13T00:00:00Z",
  "createdAt": "2021-11-12T10:00:00Z",
  "updatedAt": "2021-11-12T10:00:00Z"
}
Headers
  • Content-Type Required / string

    Payload content-type

    Values are application/json.

Body
  • key string

    The generated key. Generated by Meilisearch.

  • actions Required / array[string]

    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, tasks.get, settings.get, settings.update, stats.get, dumps.create, dumps.get, or version.

  • indexes Required / array[string]

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

  • A description for the key. null if empty.

  • expiresAt Required /

    Represent the expiration date and time as ISO-8601 format. null equals to no expiration time.

  • createdAt string

    Represent the date and time as ISO-8601 format when the API key has been created. Generated by Meilisearch.

  • Represent the date and time as ISO-8601 format when the API key has been updated. Generated by Meilisearch.

Responses
  • 200 object

    OK

    • key string

      The generated key. Generated by Meilisearch.

    • actions Required / array[string]

      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, tasks.get, settings.get, settings.update, stats.get, dumps.create, dumps.get, or version.

    • indexes Required / array[string]

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

    • A description for the key. null if empty.

    • expiresAt Required /

      Represent the expiration date and time as ISO-8601 format. null equals to no expiration time.

    • createdAt string

      Represent the date and time as ISO-8601 format when the API key has been created. Generated by Meilisearch.

    • Represent the date and time as ISO-8601 format when the API key has been updated. Generated by Meilisearch.

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

# Payload
{
  "description": "Indexing Products API key",
  "actions": [
    "documents.add"
  ],
  "indexes": [
    "products"
  ],
  "expiresAt": "2021-11-13T00:00:00Z"
}
Response example (200)
{
  "description": "Indexing Products API key",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "actions": [
    "documents.add"
  ],
  "indexes": [
    "products"
  ],
  "expiresAt": "2021-11-13T00:00:00Z",
  "createdAt": "2021-11-12T10:00:00Z",
  "updatedAt": "2021-11-12T10:00:00Z"
}
DELETE /keys/{key}
curl \
 -X DELETE https://example.meilisearch.com:7700/keys/{key} \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Update an API key

Update an API Key

Headers
  • Content-Type Required / string

    Payload content-type

    Values are application/json.

Body
  • key string

    The generated key. Generated by Meilisearch.

  • actions Required / array[string]

    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, tasks.get, settings.get, settings.update, stats.get, dumps.create, dumps.get, or version.

  • indexes Required / array[string]

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

  • A description for the key. null if empty.

  • expiresAt Required /

    Represent the expiration date and time as ISO-8601 format. null equals to no expiration time.

  • createdAt string

    Represent the date and time as ISO-8601 format when the API key has been created. Generated by Meilisearch.

  • Represent the date and time as ISO-8601 format when the API key has been updated. Generated by Meilisearch.

Responses
  • 200 object

    OK

    • key string

      The generated key. Generated by Meilisearch.

    • actions Required / array[string]

      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, tasks.get, settings.get, settings.update, stats.get, dumps.create, dumps.get, or version.

    • indexes Required / array[string]

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

    • A description for the key. null if empty.

    • expiresAt Required /

      Represent the expiration date and time as ISO-8601 format. null equals to no expiration time.

    • createdAt string

      Represent the date and time as ISO-8601 format when the API key has been created. Generated by Meilisearch.

    • Represent the date and time as ISO-8601 format when the API key has been updated. Generated by Meilisearch.

PATCH /keys/{key}
curl \
 -X PATCH https://example.meilisearch.com:7700/keys/{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)
{
  "description": "Indexing Products API key",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "actions": [
    "documents.add"
  ],
  "indexes": [
    "products"
  ],
  "expiresAt": "2021-11-13T00:00:00Z",
  "createdAt": "2021-11-12T10:00:00Z",
  "updatedAt": "2021-11-12T15:00:00Z"
}

Responses
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"
  ]
}
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

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 Required / string

    Payload content-type

    Values are application/json.

Body
Responses
POST /indexes/{indexUid}/settings
curl \
 -X POST 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}'
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
}
Response example (202)
{
  "uid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "enqueuedAt": "2021-07-19T14:31:16.920473Z"
}
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

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)
{
  "uid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "enqueuedAt": "2021-07-19T14:31:16.920473Z"
}
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 the list of synonyms of an index.

Responses
  • 200 object

    Ok

  • 401 object

    Unauthorized

    • message Required / string
    • code Required / string
    • type Required / string
  • 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

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 Required / string

    Payload content-type

    Values are application/json.

Responses
POST /indexes/{indexUid}/settings/synonyms
curl \
 -X POST 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)
{
  "uid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "enqueuedAt": "2021-07-19T14:31:16.920473Z"
}
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

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)
{
  "uid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "enqueuedAt": "2021-07-19T14:31:16.920473Z"
}
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"
}
Responses
  • 200 array[string]

    Ok

  • 401 object

    Unauthorized

    • message Required / string
    • code Required / string
    • type Required / string
  • 404

    Not Found

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

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 Required / string

    Payload content-type

    Values are application/json.

Responses
POST /indexes/{indexUid}/settings/sortable-attributes
curl \
 -X POST 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)
{
  "uid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "enqueuedAt": "2021-07-19T14:31:16.920473Z"
}
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

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

Responses
DELETE /indexes/{indexUid}/settings/sortable-attributes
curl \
 -X DELETE https://example.meilisearch.com:7700/indexes/{indexUid}/settings/sortable-attributes \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (202)
{
  "uid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "enqueuedAt": "2021-07-19T14:31:16.920473Z"
}
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 stop-words

Get the list of stop-words of an index.

Responses
  • 200 array[string]

    Ok

  • 401 object

    Unauthorized

    • message Required / string
    • code Required / string
    • type Required / string
  • 404

    Not Found

GET /indexes/{indexUid}/settings/stop-words
curl \
 -X GET https://example.meilisearch.com:7700/indexes/{indexUid}/settings/stop-words \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
[
  "of",
  "the",
  "to"
]
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 stop-words

Update the list of stop-words of an index.

If a list of stop-words already exists it will be overwritten (replaced).

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

Headers
  • Content-Type Required / string

    Payload content-type

    Values are application/json.