API 参考

欢迎使用 Meilisearch API 文档。如果您是 Meilisearch 新手，请查看我们的 快速入门指南！

Meilisearch 是一个 RESTful API。此页面描述了 API 的通用行为。

您可以在此处获取 Meilisearch OpenAPI 规范。

此 API 文档使用以下约定

• API 路径中的花括号 ({}) 表示路径参数，例如，GET /indexes/{index_uid}
• 必填字段用星号 (*) 标记
• 占位符文本使用大写字符和下划线分隔符，例如 MASTER_KEY

通过 在启动时为 Meilisearch 提供主密钥，您可以保护您的实例免受未经授权的请求。提供的主密钥必须至少为 16 个字节。从那时起，您必须包含 Authorization 标头以及有效的 API 密钥才能访问受保护的路由（所有路由，除了 /health）。

# replace the MASTER_KEY placeholder with your master key
curl \
  -X GET 'http://localhost:7700/keys' \
  -H 'Authorization: Bearer MASTER_KEY'

只能使用主密钥访问 /keys 路由。出于安全原因，我们建议对所有其他路由使用常规 API 密钥。

curl \
  -X GET 'http://<your-domain-name>/version' \
  -H 'X-Meili-API-Key: API_KEY'

要详细了解密钥和安全性，请参阅我们的安全教程。

Meilisearch 对所有返回多个资源的 GET 路由进行分页，例如 GET /indexes、GET /documents、GET /keys 等。这使您可以处理可管理的数据块。所有这些路由每页返回 20 个结果，但您可以使用 limit 查询参数对其进行配置。您可以使用 offset 在页面之间移动。

所有分页响应都包含以下字段

由于 /tasks 端点使用不同类型的分页，因此响应包含不同的字段。您可以在 任务 API 参考 中阅读更多相关信息。

参数是可以传递给 API 端点以修改其响应的选项。Meilisearch 的 API 中主要有三种类型的参数：请求体参数、路径参数和查询参数。

这些参数是 POST、PUT 和 PATCH 请求的必填部分。根据您正在修改的资源，它们接受各种各样的值和数据类型。您必须将这些参数添加到请求的数据有效负载中。

这些是您在端点路径中传递给 API 的参数。它们用于唯一标识资源。您可以有多个路径参数，例如 /indexes/{index_uid}/documents/{document_id}。

如果端点不接受任何路径参数，则此部分不会出现在该端点的文档中。

这些可选参数是一系列键值对，出现在端点问号 (?) 之后。您可以通过使用 & 符号 (&) 分隔它们来列出多个查询参数。查询参数的顺序无关紧要。它们主要与 GET 端点一起使用。

如果端点不接受任何查询参数，则此部分不会出现在该端点的文档中。

任何带有有效负载 (--data-binary) 的 API 请求都需要一个 Content-Type 标头。内容类型标头指示资源的媒体类型，帮助客户端正确处理响应主体。

Meilisearch 目前支持以下格式

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

只有 添加文档 和 更新文档 端点接受 NDJSON 和 CSV。对于所有其他端点，请使用 Content-Type: application/json。

Content-Encoding 标头指示媒体类型由给定算法压缩。压缩通过发送和接收较小的有效负载来提高传输速度并减少带宽消耗。相反，Accept-Encoding 标头指示客户端理解的压缩算法。

Meilisearch 支持以下压缩方法

• br：使用 Brotli 算法
• deflate：使用 zlib 结构和 deflate 压缩算法
• gzip：使用 gzip 算法

下面的代码示例使用 Content-Encoding: gzip 标头，表示请求主体使用 gzip 算法压缩

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

如果请求包含 Accept-Encoding 标头，则 Meilisearch 会压缩响应。下面的代码示例使用 gzip 算法

curl -sH 'Accept-encoding: gzip' 'http://localhost:7700/indexes/movies/search' | gzip -

请求体是发送到 API 的数据。它与 PUT、POST 和 PATCH 方法一起使用以创建或更新资源。您必须以 JSON 格式提供请求体。

Meilisearch 是一个**异步 API**。这意味着，对于大多数写入请求，您将收到 task 对象的摘要版本

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

您可以使用此 taskUid 获取有关 任务状态的更多详细信息。

查看有关 异步操作 的更多信息。

Meilisearch API 支持 JSON 数据类型。