> ## 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.