API reference

Welcome to the Meilisearch API documentation.

TIP

Check out the FAQ for answers to some common questions 💡

Headers

Recommended headers

Content type

Any API request with a payload (--data-binary) requires a Content-Type header. Meilisearch currently supports the following formats:

• Content-Type: application/json for JSON
• Content-Type: application/x-ndjson for NDJSON
• Content-Type: text/csv for CSV

The only endpoints which currently accept NDJSON and CSV Content-Type are the add documents and update documents endpoints. For all others, use Content-Type: application/json.

Authorization

For almost all routes, you need to be recognized by the server to check your permissions. Add your API key to your headers.

curl \
  -X GET 'http://localhost:7700/keys' \
  -H 'Authorization: Bearer MASTER_KEY'

const client = new MeiliSearch({ host: 'http://localhost:7700', apiKey: 'masterKey' })
client.getKeys()

client = Client('http://localhost:7700', 'masterKey')
client.get_keys()

$client = new Client('http://localhost:7700', 'masterKey');
$client->getKeys();

Client client = new Client(new Config("http://127.0.0.1:7700", "masterKey"));
client.getKeys();

client = MeiliSearch::Client.new('http://localhost:7700', 'masterKey')
client.keys

client := meilisearch.NewClient(meilisearch.ClientConfig{
  Host: "http://localhost:7700",
  APIKey: "masterKey",
})
client.GetKeys(nil);

MeilisearchClient client = new MeilisearchClient("http://localhost:7700", "masterKey");
var keys = await client.GetKeysAsync();

let client = Client::new("http://localhost:7700", "masterKey"); let keys = client.get_keys().await.unwrap();

var client = MeiliSearchClient('http://localhost:7700', 'masterKey');
await client.getKeys();

Please read about security keys and how to manage them for more information.

Authorization: Bearer $API_KEY

NOTE

v0.24 and below use the X-MEILI-API-KEY: apiKey authorization header.

Status codes and Meilisearch errors

Status code	Description
200	✅ Ok Everything worked as expected.
201	✅ Created The resource has been created (synchronous)
202	✅ Accepted The task has been added to the queue (asynchronous)
204	✅ No Content The resource has been deleted or no content has been returned
205	✅ Reset Content All the resources have been deleted
400	❌ Bad Request The request was unacceptable, often due to missing a required parameter
401	❌ Unauthorized No valid API key provided
403	❌ Forbidden The API key doesn't have the permissions to perform the request
404	❌ Not Found The requested resource doesn't exist

Errors

Failed requests are always accompanied by a JSON-formatted error response. Meilisearch errors can be of one of the following types:

Type	Description
invalid_request	This is due to an error in the user input. It is accompanied by the HTTP code 4xx
internal	This is due to machine or configuration constraints. The most common cause is reaching or exceeding hard limits, such as the size of the disk, the size limit of an index, etc. It is accompanied by the HTTP code 5xx
auth	This type of error is related to authentication and authorization. It is accompanied by the HTTP code 4xx

Response body:

{
  "message": "Index `movies` not found.",
  "code": "index_not_found",
  "type": "invalid_request",
  "link": "https://docs.meilisearch.com/errors#index_not_found"
}

If you're having trouble understanding an error, take a look at the complete list of code values and descriptions.

Asynchronous operations

Meilisearch is an asynchronous API. This means that in response to most write requests, you will receive a summarized version of the task object:

{
    "taskUid": 1,
    "indexUid": "movies",
    "status": "enqueued",
    "type": "indexUpdate",
    "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

See more information about asynchronous operations.