> ## Documentation Index
> Fetch the complete documentation index at: https://meilisearch-6b28dec2-mintlify-code-samples.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Consult this page for an overview of how to query Meilisearch's API, which types of parameters it supports, and how it structures its responses.

export const RouteHighlighter = ({method, path}) => <div className={`routeHighlighter routeHighlighter--${method}`}>
    <div className="routeHighlighter__method">
      {method}
    </div>
    <div className="routeHighlighter__path">
      {path}
    </div>
  </div>;

This reference describes the general behavior of Meilisearch's RESTful API.

If you are new to Meilisearch, check out the [getting started](/learn/self_hosted/getting_started_with_self_hosted_meilisearch).

## OpenAPI

Meilisearch OpenAPI specifications (`meilisearch-openapi.json`) are attached to the [latest release of Meilisearch](https://github.com/meilisearch/meilisearch/releases/tag/latest)

## Document conventions

This API documentation uses the following conventions:

* Curly braces (`{}`) in API routes represent path parameters, for example, GET `/indexes/{index_uid}`
* Required fields are marked by an asterisk (`*`)
* Placeholder text is in uppercase characters with underscore delimiters, for example, `MASTER_KEY`

## Authorization

By [providing Meilisearch with a master key at launch](/learn/security/basic_security), you protect your instance from unauthorized requests. The provided master key must be at least 16 bytes. From then on, you must include the `Authorization` header along with a valid API key to access protected routes (all routes except [`/health`](/reference/api/health).

<CodeGroup>
  ```bash cURL theme={null}
  # replace the MASTER_KEY placeholder with your master key
  curl \
    -X GET 'MEILISEARCH_URL/keys' \
    -H 'Authorization: Bearer MASTER_KEY'
  ```

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

  ```python Python theme={null}
  client = Client('http://localhost:7700', 'masterKey')
  client.get_keys()
  ```

  ```php PHP theme={null}
  $client = new Client('http://localhost:7700', 'masterKey');
  $client->getKeys();
  ```

  ```java Java theme={null}
  Client client = new Client(new Config("http://localhost:7700", "masterKey"));
  client.getKeys();
  ```

  ```ruby Ruby theme={null}
  client = MeiliSearch::Client.new('http://localhost:7700', 'masterKey')
  client.keys
  ```

  ```go Go theme={null}
  client := meilisearch.New("http://localhost:7700", meilisearch.WithAPIKey("masterKey"))
  client.GetKeys(nil);
  ```

  ```csharp C# theme={null}
  MeilisearchClient client = new MeilisearchClient("http://localhost:7700", "masterKey");
  var keys = await client.GetKeysAsync();
  ```

  ```rust Rust theme={null}
  let client = Client::new("http://localhost:7700", Some("masterKey")); let keys = client .get_keys() .await .unwrap();
  ```

  ```swift Swift theme={null}
  client = try MeiliSearch(host: "http://localhost:7700", apiKey: "masterKey")
  client.getKeys { result in
      switch result {
      case .success(let keys):
          print(keys)
      case .failure(let error):
          print(error)
      }
  }
  ```

  ```dart Dart theme={null}
  var client = MeiliSearchClient('http://localhost:7700', 'masterKey');
  await client.getKeys();
  ```
</CodeGroup>

The [`/keys`](/reference/api/keys) route can only be accessed using the master key. For security reasons, we recommend using regular API keys for all other routes.

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

  <CodeGroup>
    ```bash cURL theme={null}
    curl \
      -X GET 'http://<your-domain-name>/version' \
      -H 'X-Meili-API-Key: API_KEY'
    ```
  </CodeGroup>
</Tip>

[To learn more about keys and security, refer to our security tutorial.](/learn/security/basic_security)

## Pagination

Meilisearch paginates all GET routes that return multiple resources, for example, GET `/indexes`, GET `/documents`, GET `/keys`, etc. This allows you to work with manageable chunks of data. All these routes return 20 results per page, but you can configure it using the `limit` query parameter. You can move between pages using `offset`.

All paginated responses contain the following fields:

| Name         | Type    | Description                  |
| :----------- | :------ | :--------------------------- |
| **`offset`** | Integer | Number of resources skipped  |
| **`limit`**  | Integer | Number of resources returned |
| **`total`**  | Integer | Total number of resources    |

### `/tasks` endpoint

Since the `/tasks` endpoint uses a different type of pagination, the response contains different fields. You can read more about it in the [tasks API reference](/reference/api/tasks#get-tasks).

## Parameters

Parameters are options you can pass to an API endpoint to modify its response. There are three main types of parameters in Meilisearch's API: request body parameters, path parameters, and query parameters.

### Request body parameters

These parameters are mandatory parts of POST, PUT, and PATCH requests. They accept a wide variety of values and data types depending on the resource you're modifying. You must add these parameters to your request's data payload.

### Path parameters

These are parameters you pass to the API in the endpoint's path. They are used to identify a resource uniquely. You can have multiple path parameters, for example, `/indexes/{index_uid}/documents/{document_id}`.

If an endpoint does not take any path parameters, this section is not present in that endpoint's documentation.

### Query parameters

These optional parameters are a sequence of key-value pairs and appear after the question mark (`?`) in the endpoint. You can list multiple query parameters by separating them with an ampersand (`&`). The order of query parameters does not matter. They are mostly used with GET endpoints.

If an endpoint does not take any query parameters, this section is not present in that endpoint's documentation.

## Headers

### Content type

Any API request with a payload (`--data-binary`) requires a `Content-Type` header. Content type headers indicate the media type of the resource, helping the client process the response body correctly.

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

Only the [add documents](/reference/api/documents#add-or-replace-documents) and [update documents](/reference/api/documents#add-or-update-documents) endpoints accept NDJSON and CSV. For all others, use `Content-Type: application/json`.

### Content encoding

The `Content-Encoding` header indicates the media type is compressed by a given algorithm. Compression improves transfer speed and reduces bandwidth consumption by sending and receiving smaller payloads. The `Accept-Encoding` header, instead, indicates the compression algorithm the client understands.

Meilisearch supports the following compression methods:

* `br`: uses the [Brotli](https://en.wikipedia.org/wiki/Brotli) algorithm
* `deflate`: uses the [zlib](https://en.wikipedia.org/wiki/Zlib) structure with the [deflate](https://en.wikipedia.org/wiki/DEFLATE) compression algorithm
* `gzip`: uses the [gzip](https://en.wikipedia.org/wiki/Gzip) algorithm

#### Request compression

The code sample below uses the `Content-Encoding: gzip` header, indicating that the request body is compressed using the `gzip` algorithm:

```
 cat ~/movies.json | gzip | curl -X POST 'MEILISEARCH_URL/indexes/movies/documents' --data-binary @- -H 'Content-Type: application/json' -H 'Content-Encoding: gzip'
```

#### Response compression

Meilisearch compresses a response if the request contains the `Accept-Encoding` header. The code sample below uses the `gzip` algorithm:

```
curl -sH 'Accept-encoding: gzip' 'MEILISEARCH_URL/indexes/movies/search' | gzip -
```

### Search metadata

You may use an optional `Meili-Include-Metadata` header when performing search and multi-search requests:

```
curl -X POST 'http://localhost:7700/indexes/INDEX_NAME/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MEILISEARCH_API_KEY' \
  -H 'Meili-Include-Metadata: true' \
  -d '{"q": ""}'
```

Meilisearch Cloud includes this header by default.

Responses will include a `metadata` object:

```json theme={null}
{
  "hits": [ … ],
  "metadata": {
    "queryUid": "0199a41a-8186-70b3-b6e1-90e8cb582f35",
    "indexUid": "INDEX_NAME",
    "primaryKey": "INDEX_PRIMARY_KEY"
  }
}
```

`metadata` contains the following fields:

|     Field    |   Type  |                         Description                        |
| :----------: | :-----: | :--------------------------------------------------------: |
|  `queryUid`  | UUID v7 |               Unique identifier for the query              |
|  `indexUid`  |  String |                      Index identifier                      |
| `primaryKey` |  String |     Primary key field name, if index has a primary key     |
|   `remote`   |  String | Remote instance name, if request targets a remote instance |

<Note>
  A search refers to a single HTTP search request. Every search request is assigned a `requestUid`. A query UID is a combination of `q` and `indexUid`.

  In the context of multi-search, for any given `searchUid` there may be multiple `queryUid` values.
</Note>

## Request body

The request body is data sent to the API. It is used with PUT, POST, and PATCH methods to create or update a resource. You must provide request bodies in JSON.

## Response body

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

```json theme={null}
{
    "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](/reference/api/tasks#get-one-task).

See more information about [asynchronous operations](/learn/async/asynchronous_operations).

## Data types

The Meilisearch API supports [JSON data types](https://www.w3schools.com/js/js_json_datatypes.asp).