Collections API

Collection Management

collection 管理的基础 URL 与 Management API 共享，为 https://management-api.x.ai/。您必须使用 xAI Management API Key 进行身份验证，并在头部中添加 Authorization: Bearer <your xAI Management API key>。

NOTE

有关配置 xAI Management API key 和使用 Management API 的更多详细信息，您可以访问

Using Management API

POST /v1/collections

创建一个集合。

Request Body

team_id (string) — 将拥有此新集合的团队 ID。如果未提供，团队 ID 将从您的请求凭据中派生。
collection_name (string, required) — 用于新集合的名称。
index_configuration (object)
- model_name (string) — 将进行转换的嵌入模型。
chunk_configuration (object)
- chars_configuration (object)
  - max_chunk_size_chars (integer) — 每个块的最大长度。
  - chunk_overlap_chars (integer) — 块之间的重叠，两侧都有。
- tokens_configuration (object)
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - chunk_overlap_tokens (integer) — 块之间的重叠，两侧都有。
  - encoding_name (string) — 用于分词器的编码名称。
- ast_configuration (object) — 已弃用：请使用 CodeTokensConfiguration 或 CodeCharsConfiguration。
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - encoding_name (string) — 用于分词器的编码名称。
- table_configuration (object)
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - encoding_name (string) — 用于分词器的编码名称。
- markdown_tokens_configuration (object)
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - chunk_overlap_tokens (integer) — 块之间的重叠，两侧都有。
  - encoding_name (string) — 用于分词器的编码名称。
- markdown_chars_configuration (object)
  - max_chunk_size_chars (integer) — 每个块的最大长度。
  - chunk_overlap_chars (integer) — 块之间的重叠，两侧都有。
- code_tokens_configuration (object)
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - chunk_overlap_tokens (integer) — 块之间的重叠，两侧都有。
  - encoding_name (string) — 用于分词器的编码名称。
- code_chars_configuration (object)
  - max_chunk_size_chars (integer) — 每个块的最大长度。
  - chunk_overlap_chars (integer) — 块之间的重叠，两侧都有。
- bytes_configuration (object)
  - max_chunk_size_bytes (integer) — 每个块的最大长度（字节）。
  - chunk_overlap_bytes (integer) — 块之间的重叠（字节）。
- strip_whitespace (boolean) — 移除前导/尾随空白。
- inject_name_into_chunks (boolean) — 将名称注入到生成的块中。
metric_space ("HNSW_METRIC_UNKNOWN" | "HNSW_METRIC_COSINE" | "HNSW_METRIC_EUCLIDEAN" | "HNSW_METRIC_INNER_PRODUCT") — HNSW 索引的距离空间。
version (integer) — 仅限内部使用。 Collection API 使用的版本号。这是一个仅内部使用的设置，因此可以保持模糊（无枚举）。
field_definitions (array<object>)
- key (string, required) — 字段的键/名称（例如，"title"、"author"、"isbn"）。
- required (boolean) — 如果为 true，则每个添加到集合的文档必须提供此字段。缺少必需字段的文档将在上传时被拒绝。
- inject_into_chunk (boolean) — 如果为 true，此字段的值将被注入到从文档生成的每个块的开始（用于上下文检索）。通过提供有关文档的上下文来提高检索准确性。
- unique (boolean) — 如果为 true，此字段的值在此集合的所有文档中必须唯一。重复值将被拒绝。
- description (string) — 关于此字段所代表内容的可选描述。
collection_description (string) — 向用户和代理显示的友好描述。

Response Body

collection_id (string) — 表示集合 ID 的 UUIDv4。
collection_name (string) — 集合的名称。
created_at (string) — 文档创建时的 Unix 时间戳。
index_configuration (object)
- model_name (string) — 将进行转换的嵌入模型。
chunk_configuration (object)
- chars_configuration (object)
  - max_chunk_size_chars (integer) — 每个块的最大长度。
  - chunk_overlap_chars (integer) — 块之间的重叠，两侧都有。
- tokens_configuration (object)
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - chunk_overlap_tokens (integer) — 块之间的重叠，两侧都有。
  - encoding_name (string) — 用于分词器的编码名称。
- ast_configuration (object) — 已弃用：请使用 CodeTokensConfiguration 或 CodeCharsConfiguration。
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - encoding_name (string) — 用于分词器的编码名称。
- table_configuration (object)
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - encoding_name (string) — 用于分词器的编码名称。
- markdown_tokens_configuration (object)
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - chunk_overlap_tokens (integer) — 块之间的重叠，两侧都有。
  - encoding_name (string) — 用于分词器的编码名称。
- markdown_chars_configuration (object)
  - max_chunk_size_chars (integer) — 每个块的最大长度。
  - chunk_overlap_chars (integer) — 块之间的重叠，两侧都有。
- code_tokens_configuration (object)
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - chunk_overlap_tokens (integer) — 块之间的重叠，两侧都有。
  - encoding_name (string) — 用于分词器的编码名称。
- code_chars_configuration (object)
  - max_chunk_size_chars (integer) — 每个块的最大长度。
  - chunk_overlap_chars (integer) — 块之间的重叠，两侧都有。
- bytes_configuration (object)
  - max_chunk_size_bytes (integer) — 每个块的最大长度（字节）。
  - chunk_overlap_bytes (integer) — 块之间的重叠（字节）。
- strip_whitespace (boolean) — 移除前导/尾随空白。
- inject_name_into_chunks (boolean) — 将名称注入到生成的块中。
documents_count (integer) — 集合包含的文件数量。
field_definitions (array<object>) — 此集合中文档的字段定义。定义文档可以具有的字段及其约束。
- key (string, required) — 字段的键/名称（例如，"title"、"author"、"isbn"）。
- required (boolean) — 如果为 true，则每个添加到集合的文档必须提供此字段。缺少必需字段的文档将在上传时被拒绝。
- inject_into_chunk (boolean) — 如果为 true，此字段的值将被注入到从文档生成的每个块的开始（用于上下文检索）。通过提供有关文档的上下文来提高检索准确性。
- unique (boolean) — 如果为 true，此字段的值在此集合的所有文档中必须唯一。重复值将被拒绝。
- description (string) — 关于此字段所代表内容的可选描述。
collection_description (string) — 集合的可选描述。

Request example:

json

{
  "collection_name": "SEC Filings",
  "index_configuration": {
    "model_name": "grok-embedding-small"
  },
  "chunk_configuration": {
    "tokens_configuration": {
      "max_chunk_size_tokens": 1024,
      "chunk_overlap_tokens": 200,
      "encoding_name": "o200k_base"
    },
    "strip_whitespace": true
  },
  "collection_description": "Filings from the SEC for financial analysis"
}

Response example:

json

{
  "collection_id": "collection_80100614-300c-4609-959b-a138fa90f542",
  "collection_name": "SEC Filings",
  "created_at": "2025-09-16T18:36:09.790629Z",
  "index_configuration": {
    "model_name": "grok-embedding-small"
  },
  "chunk_configuration": {
    "tokens_configuration": {
      "max_chunk_size_tokens": 1024,
      "chunk_overlap_tokens": 200,
      "encoding_name": "o200k_base"
    },
    "strip_whitespace": true,
    "inject_name_into_chunks": false
  },
  "documents_count": 0,
  "collection_description": "Filings from the SEC for financial analysis"
}

GET /v1/collections

列出团队拥有的所有集合。

Query Parameters

team_id (string) — 拥有所列出集合的团队 ID。如果未提供，团队 ID 将从您的请求凭据中派生。
limit (integer) — 对返回对象数量的限制。每次请求最多 100 个项目。如果未提供，默认设置为 100 个项目。
order ("ORDERING_UNKNOWN" | "ORDERING_ASCENDING" | "ORDERING_DESCENDING") — 对返回的集合进行排序的顺序。如果未提供，默认顺序为降序。
sort_by ("COLLECTIONS_SORT_BY_NAME" | "COLLECTIONS_SORT_BY_AGE") — 将用于对集合进行排序的参数。如果未提供，默认按 `collection_name` 排序。
pagination_token (string) — 用于检索下一页的可选令牌。由先前 `ListCollectionsResponse` 中的 `pagination_token` 提供。
filter (string) — 缩小结果的过滤表达式。支持对以下内容进行过滤：collection_id、collection_name（部分字符串匹配）、created_at、documents_count 示例： - 'collection_id = "collection_123"' - 'collection_name:"SEC" AND documents_count:>10' - 'collection_name = "report"'（部分匹配） - 'created_at:>2025-01-01T00:00:00Z'

Response Body

collections (array<object>) — 集合列表。
- collection_id (string) — 表示集合 ID 的 UUIDv4。
- collection_name (string) — 集合的名称。
- created_at (string) — 文档创建时的 Unix 时间戳。
- index_configuration (object)
  - model_name (string) — 将进行转换的嵌入模型。
- chunk_configuration (object)
  - chars_configuration (object)
    - max_chunk_size_chars (integer) — 每个块的最大长度。
    - chunk_overlap_chars (integer) — 块之间的重叠，两侧都有。
  - tokens_configuration (object)
    - max_chunk_size_tokens (integer) — 每个块的最大长度。
    - chunk_overlap_tokens (integer) — 块之间的重叠，两侧都有。
    - encoding_name (string) — 用于分词器的编码名称。
  - ast_configuration (object) — 已弃用：请使用 CodeTokensConfiguration 或 CodeCharsConfiguration。
    - max_chunk_size_tokens (integer) — 每个块的最大长度。
    - encoding_name (string) — 用于分词器的编码名称。
  - table_configuration (object)
    - max_chunk_size_tokens (integer) — 每个块的最大长度。
    - encoding_name (string) — 用于分词器的编码名称。
  - markdown_tokens_configuration (object)
    - max_chunk_size_tokens (integer) — 每个块的最大长度。
    - chunk_overlap_tokens (integer) — 块之间的重叠，两侧都有。
    - encoding_name (string) — 用于分词器的编码名称。
  - markdown_chars_configuration (object)
    - max_chunk_size_chars (integer) — 每个块的最大长度。
    - chunk_overlap_chars (integer) — 块之间的重叠，两侧都有。
  - code_tokens_configuration (object)
    - max_chunk_size_tokens (integer) — 每个块的最大长度。
    - chunk_overlap_tokens (integer) — 块之间的重叠，两侧都有。
    - encoding_name (string) — 用于分词器的编码名称。
  - code_chars_configuration (object)
    - max_chunk_size_chars (integer) — 每个块的最大长度。
    - chunk_overlap_chars (integer) — 块之间的重叠，两侧都有。
  - bytes_configuration (object)
    - max_chunk_size_bytes (integer) — 每个块的最大长度（字节）。
    - chunk_overlap_bytes (integer) — 块之间的重叠（字节）。
  - strip_whitespace (boolean) — 移除前导/尾随空白。
  - inject_name_into_chunks (boolean) — 将名称注入到生成的块中。
- documents_count (integer) — 集合包含的文件数量。
- field_definitions (array<object>) — 此集合中文档的字段定义。定义文档可以具有的字段及其约束。
  - key (string, required) — 字段的键/名称（例如，"title"、"author"、"isbn"）。
  - required (boolean) — 如果为 true，则每个添加到集合的文档必须提供此字段。缺少必需字段的文档将在上传时被拒绝。
  - inject_into_chunk (boolean) — 如果为 true，此字段的值将被注入到从文档生成的每个块的开始（用于上下文检索）。通过提供有关文档的上下文来提高检索准确性。
  - unique (boolean) — 如果为 true，此字段的值在此集合的所有文档中必须唯一。重复值将被拒绝。
  - description (string) — 关于此字段所代表内容的可选描述。
- collection_description (string) — 集合的可选描述。
pagination_token (string) — 应在下一个 `ListCollectionsRequest` 的 `pagination_token` 中发送的令牌，用于检索下一页。

Response example:

json

{
  "collections": [
    {
      "collection_id": "collection_80100614-300c-4609-959b-a138fa90f542",
      "collection_name": "SEC Filings",
      "created_at": "2025-09-16T18:36:09.790629Z",
      "index_configuration": {
        "model_name": "grok-embedding-small"
      },
      "chunk_configuration": {
        "tokens_configuration": {
          "max_chunk_size_tokens": 1024,
          "chunk_overlap_tokens": 200,
          "encoding_name": "o200k_base"
        },
        "strip_whitespace": true,
        "inject_name_into_chunks": false
      },
      "documents_count": 0,
      "collection_type": "text",
      "collection_description": "Filings from the SEC for financial analysis"
    }
  ]
}

GET /v1/collections/{collection_id}

获取集合的元数据。

Path Parameters

collection_id (string, required) — 要请求的集合 ID。

Query Parameters

team_id (string) — 拥有该集合的团队 ID。如果未提供，团队 ID 将从您的请求凭据中派生。

Response Body

collection_id (string) — 表示集合 ID 的 UUIDv4。
collection_name (string) — 集合的名称。
created_at (string) — 文档创建时的 Unix 时间戳。
index_configuration (object)
- model_name (string) — 将进行转换的嵌入模型。
chunk_configuration (object)
- chars_configuration (object)
  - max_chunk_size_chars (integer) — 每个块的最大长度。
  - chunk_overlap_chars (integer) — 块之间的重叠，两侧都有。
- tokens_configuration (object)
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - chunk_overlap_tokens (integer) — 块之间的重叠，两侧都有。
  - encoding_name (string) — 用于分词器的编码名称。
- ast_configuration (object) — 已弃用：请使用 CodeTokensConfiguration 或 CodeCharsConfiguration。
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - encoding_name (string) — 用于分词器的编码名称。
- table_configuration (object)
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - encoding_name (string) — 用于分词器的编码名称。
- markdown_tokens_configuration (object)
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - chunk_overlap_tokens (integer) — 块之间的重叠，两侧都有。
  - encoding_name (string) — 用于分词器的编码名称。
- markdown_chars_configuration (object)
  - max_chunk_size_chars (integer) — 每个块的最大长度。
  - chunk_overlap_chars (integer) — 块之间的重叠，两侧都有。
- code_tokens_configuration (object)
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - chunk_overlap_tokens (integer) — 块之间的重叠，两侧都有。
  - encoding_name (string) — 用于分词器的编码名称。
- code_chars_configuration (object)
  - max_chunk_size_chars (integer) — 每个块的最大长度。
  - chunk_overlap_chars (integer) — 块之间的重叠，两侧都有。
- bytes_configuration (object)
  - max_chunk_size_bytes (integer) — 每个块的最大长度（字节）。
  - chunk_overlap_bytes (integer) — 块之间的重叠（字节）。
- strip_whitespace (boolean) — 移除前导/尾随空白。
- inject_name_into_chunks (boolean) — 将名称注入到生成的块中。
documents_count (integer) — 集合包含的文件数量。
field_definitions (array<object>) — 此集合中文档的字段定义。定义文档可以具有的字段及其约束。
- key (string, required) — 字段的键/名称（例如，"title"、"author"、"isbn"）。
- required (boolean) — 如果为 true，则每个添加到集合的文档必须提供此字段。缺少必需字段的文档将在上传时被拒绝。
strip_whitespace (boolean) — 移除前导/尾随空白。
inject_name_into_chunks (boolean) — 将名称注入到生成的块中。
field_definition_updates (array<object>) — 要应用于此集合的字段定义更新（ADD 或 DELETE）。
- field_definition (object, required) — 可附加到集合中文档的字段定义。字段定义指定了集合中文档元数据的约束和行为。
  - key (string, required) — 字段的键/名称（例如，"title"、"author"、"isbn"）。
  - required (boolean) — 如果为 true，则每个添加到集合的文档都必须提供此字段。缺少必填字段的文档将在上传时被拒绝。
  - inject_into_chunk (boolean) — 如果为 true，此字段的值将被注入到从文档生成的每个块的开始处（用于上下文检索）。通过提供文档上下文来提高检索准确性。
  - unique (boolean) — 如果为 true，此字段的值必须在此集合的所有文档中唯一。重复值将被拒绝。
  - description (string) — 关于此字段所代表内容的可选描述。
- operation ("FIELD_DEFINITION_ADD" | "FIELD_DEFINITION_DELETE") — 对集合字段定义执行的操作。
  - FIELD_DEFINITION_ADD: 添加新的字段定义或更新现有定义。如果字段键已存在，则将更新该定义。注意：不允许使用 `required=true` 的新字段（现有文档将无法通过验证）。 - FIELD_DEFINITION_DELETE: 删除现有字段定义。级联行为：同时从集合中的所有文档中删除该字段值。
collection_description (string) — 对集合的可选描述。

响应正文

collection_id (string) — 表示集合 ID 的 UUIDv4。
collection_name (string) — 集合的名称。
created_at (string) — 文档创建时的 Unix 时间戳。
index_configuration (object)
- model_name (string) — 将进行转换的嵌入模型。
chunk_configuration (object)
- chars_configuration (object)
  - max_chunk_size_chars (integer) — 每个块的最大长度。
  - chunk_overlap_chars (integer) — 块之间的重叠，两侧。
- tokens_configuration (object)
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - chunk_overlap_tokens (integer) — 块之间的重叠，两侧。
  - encoding_name (string) — 用于分词器的编码名称。
- ast_configuration (object) — 已弃用：请改用 CodeTokensConfiguration 或 CodeCharsConfiguration。
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - encoding_name (string) — 用于分词器的编码名称。
- table_configuration (object)
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - encoding_name (string) — 用于分词器的编码名称。
- markdown_tokens_configuration (object)
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - chunk_overlap_tokens (integer) — 块之间的重叠，两侧。
  - encoding_name (string) — 用于分词器的编码名称。
- markdown_chars_configuration (object)
  - max_chunk_size_chars (integer) — 每个块的最大长度。
  - chunk_overlap_chars (integer) — 块之间的重叠，两侧。
- code_tokens_configuration (object)
  - max_chunk_size_tokens (integer) — 每个块的最大长度。
  - chunk_overlap_tokens (integer) — 块之间的重叠，两侧。
  - encoding_name (string) — 用于分词器的编码名称。
- code_chars_configuration (object)
  - max_chunk_size_chars (integer) — 每个块的最大长度。
  - chunk_overlap_chars (integer) — 块之间的重叠，两侧。
- bytes_configuration (object)
  - max_chunk_size_bytes (integer) — 每个块的最大长度（字节）。
  - chunk_overlap_bytes (integer) — 块之间的重叠（字节）。
- strip_whitespace (boolean) — 移除前导/尾随空白。
- inject_name_into_chunks (boolean) — 将名称注入到生成的块中。
documents_count (integer) — 集合包含的文件数量。
field_definitions (array<object>) — 此集合中文档的字段定义。定义文档可以具有哪些字段及其约束。
- key (string, required) — 字段的键/名称（例如，"title"、"author"、"isbn"）。
- required (boolean) — 如果为 true，则每个添加到集合的文档都必须提供此字段。缺少必填字段的文档将在上传时被拒绝。
- inject_into_chunk (boolean) — 如果为 true，此字段的值将被注入到从文档生成的每个块的开始处（用于上下文检索）。通过提供文档上下文来提高检索准确性。
- unique (boolean) — 如果为 true，此字段的值必须在此集合的所有文档中唯一。重复值将被拒绝。
- description (string) — 关于此字段所代表内容的可选描述。
collection_description (string) — 对集合的可选描述。

请求示例：

json

{
  "collectionName": "SEC Filings (New)",
  "chunkConfiguration": {
    "tokensConfiguration": {
      "maxChunkSizeTokens": 1024,
      "chunkOverlapTokens": 200,
      "encodingName": "o200k_base"
    },
    "stripWhitespace": true,
    "injectNameIntoChunks": false
  },
  "collectionDescription": "Updated description of the collection"
}

响应示例：

json

{
  "collection_id": "collection_80100614-300c-4609-959b-a138fa90f542",
  "collection_name": "SEC Filings",
  "created_at": "2025-09-16T18:36:09.790629Z",
  "index_configuration": {
    "model_name": "grok-embedding-small"
  },
  "chunk_configuration": {
    "tokens_configuration": {
      "max_chunk_size_tokens": 1024,
      "chunk_overlap_tokens": 200,
      "encoding_name": "o200k_base"
    },
    "strip_whitespace": true,
    "inject_name_into_chunks": false
  },
  "documents_count": 0,
  "collection_description": "Filings from the SEC for financial analysis"
}

POST /v1/collections/{collection_id}/documents/{file_id}

将文档添加到集合中。

路径参数

collection_id (string, required) — 将添加此文档的集合 ID。
file_id (string, required) — 用于此请求的文档 ID。

请求正文

team_id (string) — 文档所属的团队 ID。如果未提供，团队 ID 将从您的请求凭据中派生。
fields (object) — 要在此新集合中添加到此文档的用户定义字段。

请求示例：

json

{
  "fields": {
    "type": "10-Q"
  }
}

响应示例：

json

{}

GET /v1/collections/{collection_id}/documents

列出集合中的文档。

路径参数

collection_id (string, required) — 要列出文档的集合 ID。

查询参数

team_id (string) — 拥有文档的团队 ID。如果未提供，团队 ID 将从您的请求凭据中派生。
limit (integer) — 返回对象数量的限制。每次请求最多 100 个项目。如果未提供，默认设置为 100 个项目。
order ("ORDERING_UNKNOWN" | "ORDERING_ASCENDING" | "ORDERING_DESCENDING") — 排序返回文档的顺序。如果未提供，默认顺序为降序。
sort_by ("DOCUMENTS_SORT_BY_NAME" | "DOCUMENTS_SORT_BY_SIZE" | "DOCUMENTS_SORT_BY_AGE") — 文档将按其排序的参数。如果未提供，默认按 `name` 排序。
pagination_token (string) — 用于检索下一页的可选令牌。由先前 `ListDocumentsResponse` 中的 `pagination_token` 提供。
name (string) — 要获取的文档名称。已弃用：请改用 filter 字段，格式为 "name:value"
filter (string) — 缩小结果的过滤表达式。支持对文件元数据（name、content_type、size_bytes、created_at）和文档字段（status、fields.{key}）进行过滤示例： - 'status:DOCUMENT_STATUS_PROCESSED' - 'name:"quarterly" AND status:!DOCUMENT_STATUS_FAILED' - 'fields.isbn:"978-1-234567-89-0"' - 'size_bytes:>5000000 AND content_type:application/pdf'

响应正文

documents (array<object>) — 文档列表。
- file_metadata (object) — 上传文件的元数据。
  - file_id (string) — 文档 ID。
  - name (string) — 文档的名称。
  - size_bytes (string) — 文档的大小（字节）。
  - content_type (string) — MIME 类型。
  - created_at (string) — 文档创建时的 Unix 时间戳。
  - expires_at (string) — 文档将过期时的 Unix 时间戳。
  - hash (string)
  - upload_status (string)
  - upload_error_message (string) — 上传失败时的错误消息。
  - processing_status (string) — 文件的处理状态（pending、processing、complete、failed、skipped）。
  - file_path (string) — 可选：文件的分层路径（例如，"folder1/subfolder"）。这是相对于团队根目录的，不包括文件名。
- fields (object)
- status ("DOCUMENT_STATUS_UNKNOWN" | "DOCUMENT_STATUS_PROCESSING" | "DOCUMENT_STATUS_PROCESSED" | "DOCUMENT_STATUS_FAILED")
- error_message (string) — 处理过程中发生的任何错误。
- last_indexed_at (string) — 此文档上次索引的时间戳。如果尚未索引，则为空。
pagination_token (string) — 将在下一个 `ListDocumentsRequest` 的 `pagination_token` 中发送的令牌，用于检索下一页。

响应示例：

json

{
  "documents": [
    {
      "file_metadata": {
        "file_id": "file_94847856-a56f-4b1e-82dd-7fe0b3af43d9",
        "name": "tsla-20250630.txt",
        "size_bytes": "119237",
        "content_type": "text/plain",
        "created_at": "2025-09-16T19:06:53.472088Z",
        "expires_at": null,
        "hash": "a15b2225695f242af60e5d99a7455b0a2e371dac88283401ebc013dba1dfbc84"
      },
      "fields": {
        "type": "10-Q"
      },
      "status": "DOCUMENT_STATUS_PROCESSED",
      "error_message": ""
    }
  ]
}

GET /v1/collections/{collection_id}/documents/{file_id}

检索集合中的文档元数据。

路径参数

collection_id (string, required) — 此文档所属的集合 ID。
file_id (string, required) — 用于此请求的文档 ID。

查询参数

team_id (string) — 文档所属的团队 ID。如果未提供，团队 ID 将从您的请求凭据中派生。

响应正文

file_metadata (object) — 上传文件的元数据。
- file_id (string) — 文档 ID。
- name (string) — 文档的名称。
- size_bytes (string) — 文档的大小（字节）。
- content_type (string) — MIME 类型。
- created_at (string) — 文档创建时的 Unix 时间戳。
- expires_at (string) — 文档将过期时的 Unix 时间戳。
- hash (string)
- upload_status (string)
- upload_error_message (string) — 上传失败时的错误消息。
- processing_status (string) — 文件的处理状态（pending、processing、complete、failed、skipped）。
- file_path (string) — 可选：文件的分层路径（例如，"folder1/subfolder"）。这是相对于团队根目录的，不包括文件名。
fields (object)
status ("DOCUMENT_STATUS_UNKNOWN" | "DOCUMENT_STATUS_PROCESSING" | "DOCUMENT_STATUS_PROCESSED" | "DOCUMENT_STATUS_FAILED")
error_message (string) — 处理过程中发生的任何错误。
last_indexed_at (string) — 此文档上次索引的时间戳。如果尚未索引，则为空。

响应示例：

json

{
  "file_metadata": {
    "file_id": "file_94847856-a56f-4b1e-82dd-7fe0b3af43d9",
    "name": "tsla-20250630.txt",
    "size_bytes": "119237",
    "content_type": "text/plain",
    "created_at": "2025-09-16T19:06:53.472088Z",
    "expires_at": null,
    "hash": "a15b2225695f242af60e5d99a7455b0a2e371dac88283401ebc013dba1dfbc84"
  },
  "fields": {
    "type": "10-Q"
  },
  "status": "DOCUMENT_STATUS_PROCESSED",
  "error_message": ""
}

PATCH /v1/collections/{collection_id}/documents/{file_id}

为给定文档重新生成索引。

路径参数

collection_id (string, required) — 包含文档的集合 ID。
file_id (string, required) — 要更新的文件 ID。

查询参数

team_id (string) — 拥有文档的团队 ID。如果未提供，团队 ID 将从您的请求凭据中派生。

响应示例：

json

{}

DELETE /v1/collections/{collection_id}/documents/{file_id}

从集合中移除文档。

路径参数

collection_id (string, required) — 将从中移除文档的集合 ID。
file_id (string, required) — 用于此请求的文档文件 ID。

查询参数

team_id (string) — 拥有集合的团队 ID。如果未提供，团队 ID 将从您的请求凭据中派生。

响应示例：

json

{}

GET /v1/collections/{collection_id}/documents:batchGet

批量请求获取文档元数据。

路径参数

collection_id (string, required) — 包含文档的集合 ID。

查询参数

team_id (string) — 拥有文档的团队 ID。如果为 `None`，团队 ID 将从您的请求凭据中派生。
file_ids (array<string>, required) — 从中获取文档元数据的文件 ID。

响应正文

documents (array<object>) — 请求的文档元数据。
- file_metadata (object) — 上传文件的元数据。
  - file_id (string) — 文档 ID。
  - name (string) — 文档的名称。
  - size_bytes (string) — 文档的大小（字节）。
  - content_type (string) — MIME 类型。
  - created_at (string) — 文档创建时的 Unix 时间戳。
  - expires_at (string) — 文档将过期时的 Unix 时间戳。
  - hash (string)
  - upload_status (string)
  - upload_error_message (string) — 上传失败时的错误消息。
  - processing_status (string) — 文件的处理状态（pending、processing、complete、failed、skipped）。
  - file_path (string) — 可选：文件的分层路径（例如，"folder1/subfolder"）。这是相对于团队根目录的，不包括文件名。
- fields (object)
- status ("DOCUMENT_STATUS_UNKNOWN" | "DOCUMENT_STATUS_PROCESSING" | "DOCUMENT_STATUS_PROCESSED" | "DOCUMENT_STATUS_FAILED")
- error_message (string) — 处理过程中发生的任何错误。
- last_indexed_at (string) — 此文档上次索引的时间戳。如果尚未索引，则为空。

响应示例：

json

{
  "documents": [
    {
      "file_metadata": {
        "file_id": "file_94847856-a56f-4b1e-82dd-7fe0b3af43d9",
        "name": "tsla-20250630.txt",
        "size_bytes": "119237",
        "content_type": "text/plain",
        "created_at": "2025-09-16T19:06:53.472088Z",
        "expires_at": null,
        "hash": "a15b2225695f242af60e5d99a7455b0a2e371dac88283401ebc013dba1dfbc84"
      },
      "fields": {},
      "status": "DOCUMENT_STATUS_PROCESSED",
      "error_message": ""
    }
  ]
}

Collections API ​

Collection Management ​

POST /v1/collections ​

Request Body ​

Response Body ​

GET /v1/collections ​

Query Parameters ​

Response Body ​

GET /v1/collections/{collection_id} ​

Path Parameters ​

Query Parameters ​

Response Body ​

响应正文 ​

POST /v1/collections/{collection_id}/documents/{file_id} ​

路径参数 ​

请求正文 ​

GET /v1/collections/{collection_id}/documents ​

路径参数 ​

查询参数 ​

响应正文 ​

GET /v1/collections/{collection_id}/documents/{file_id} ​

路径参数 ​

查询参数 ​

响应正文 ​

PATCH /v1/collections/{collection_id}/documents/{file_id} ​

路径参数 ​

查询参数 ​

DELETE /v1/collections/{collection_id}/documents/{file_id} ​

路径参数 ​

查询参数 ​

GET /v1/collections/{collection_id}/documents:batchGet ​

路径参数 ​

查询参数 ​

响应正文 ​

Collections API

Collection Management

POST /v1/collections

Request Body

Response Body

GET /v1/collections

Query Parameters

Response Body

GET /v1/collections/{collection_id}

Path Parameters

Query Parameters

Response Body

响应正文

POST /v1/collections/{collection_id}/documents/{file_id}

路径参数

请求正文

GET /v1/collections/{collection_id}/documents

路径参数

查询参数

响应正文

GET /v1/collections/{collection_id}/documents/{file_id}

路径参数

查询参数

响应正文

PATCH /v1/collections/{collection_id}/documents/{file_id}

路径参数

查询参数

DELETE /v1/collections/{collection_id}/documents/{file_id}

路径参数

查询参数

GET /v1/collections/{collection_id}/documents:batchGet

路径参数

查询参数

响应正文