> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 获取 AceDataCloud 平台文档列表

> Platform 集成指南 - Ace Data Cloud

分页返回当前站点可见的开发者文档，可用于搜索、索引或在客户端自行构建导航。列表当前包含每篇文档的 `content` 和嵌套父级信息，响应可能较大。

## 接口概览

| 项 | 内容 |
| - | - |
| 方法 | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/documents/` |
| 鉴权 | 公开；非管理员看不到 private 文档 |
| 分页 | `count` + `items` |

## 查询参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
| - | - | - | - | - |
| `id` | UUID | 否 | — | 按文档 ID 筛选；支持重复参数 |
| `private` | boolean | 否 | — | 按 private 状态筛选；非管理员仍无法看到私有文档 |
| `type` | string | 否 | — | 按 Document 的实际 `type` 值精确筛选 |
| `tag` | string | 否 | — | 按标签筛选 |
| `limit` | integer | 否 | 10 | 每页条数，最大 100 |
| `offset` | integer | 否 | 0 | 分页偏移量 |
| `ordering` | string | 否 | `rank` | 仅支持按 `rank` 排序；前缀 `-` 表示倒序 |

当前列表接口不支持 `alias` 或 `parent_id` 过滤。已知 alias 时直接调用[文档详情](https://platform.acedata.cloud/documents/platform-document-detail)；构建树形导航时一次分页拉取后，使用每项 `parent.id` 在客户端分组。

## 请求示例

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/documents/' \
  --data-urlencode 'tag=development' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'ordering=rank' \
  -H 'Accept: application/json'
```

```python theme={null}
import requests

response = requests.get(
    "https://platform.acedata.cloud/api/v1/documents/",
    params={"tag": "development", "limit": 100, "offset": 0},
    timeout=30,
)
response.raise_for_status()
data = response.json()
for document in data["items"]:
    parent = document.get("parent") or {}
    print(document["alias"], parent.get("alias"))
```

## 响应结构

```json theme={null}
{
  "count": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "alias": "platform-token",
      "name": "Document of Platform Token",
      "title": "管理 AceDataCloud 平台账户令牌（Account Token）",
      "content": "# 管理 AceDataCloud 平台账户令牌……",
      "type": "Text",
      "private": false,
      "primary_only": false,
      "rank": 2400,
      "tags": [
        "development"
      ],
      "parent": {
        "id": "00000000-0000-4000-8000-000000000002",
        "alias": "platform",
        "title": "AceDataCloud 平台"
      },
      "sibling": null,
      "api_id": null,
      "proxy_id": null,
      "api_method": null,
      "metadata": null,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ]
}
```

列表使用 `DocumentIndexSerializer`，当前会返回模型字段及嵌套关系；关联 API 文档还可能带 `api_method`。字段可能向后兼容地增加，客户端应按需读取。需要 `children`、解析后的内容语言和内容哈希时，使用详情接口。

对于关联源文档的公开记录，`content_source` 提供源文档标识、源内容哈希、所请求的语言、翻译更新时间及 `ready`、`stale`、`missing`、`missing_source` 或 `ambiguous` 状态；其他记录该字段为 `null`。`ready` 时的 `content_hash` 对应该语言译文。正文仍按原有规则展示，包括缺少译文时的语言回退；需要同步文档的客户端应同时检查状态和哈希，不能仅凭正文非空判断已更新。

## 使用建议

* 响应含正文，批量同步时使用分页并设置合理超时，不要并发抓取同一页。
* alias 是公开页面 URL 的稳定标识；已知 alias 时直接请求 `/api/v1/documents/{alias}`。
* 当前接口无法按父级服务端过滤；构建导航时在客户端按 `parent.id` 分组。

## 相关接口

* [获取 AceDataCloud 平台文档详情](https://platform.acedata.cloud/documents/platform-document-detail)
* [获取 AceDataCloud 平台 API 详情](https://platform.acedata.cloud/documents/platform-api-detail)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.