> ## 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 API guide - Ace Data Cloud

Посторінково повертає документи розробника, видимі на поточному сайті, які можна використовувати для пошуку, індексації або самостійної побудови навігації на клієнті. Наразі список містить `content` кожного документа та вкладену інформацію про батьківський елемент, відповідь може бути великою.

## Огляд інтерфейсу

| Пункт | Вміст |
| - | - |
| Метод | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/documents/` |
| Авторизація | Публічний; неадміністратори не можуть бачити private документи |
| Пагінація | `count` + `items` |

## Параметри запиту

| Параметр | Тип | Обов’язковий | За замовчуванням | Опис |
| - | - | - | - | - |
| `id` | UUID | Ні | — | Фільтрація за ID документа; підтримує повторювані параметри |
| `private` | boolean | Ні | — | Фільтрація за статусом private; неадміністратори все одно не можуть бачити приватні документи |
| `type` | string | Ні | — | Точна фільтрація за фактичним значенням `type` Document |
| `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`. `content_hash` у стані `ready` відповідає перекладу цією мовою. Основний текст і надалі відображається за початковими правилами, включно з мовним резервним варіантом за відсутності перекладу; клієнти, яким потрібно синхронізувати документи, повинні одночасно перевіряти статус і хеш та не можуть визначати оновлення лише за непорожнім основним текстом.

## Рекомендації щодо використання

* Відповідь містить основний текст, тому під час пакетної синхронізації використовуйте пагінацію та встановлюйте розумний тайм-аут, не завантажуйте одну й ту саму сторінку паралельно.
* alias є стабільним ідентифікатором URL публічної сторінки; якщо alias відомий, безпосередньо запитуйте `/api/v1/documents/{alias}`.
* Поточний інтерфейс не може фільтрувати за батьківським елементом на сервері; під час побудови навігації групуйте на клієнті за `parent.id`.

## Пов’язані інтерфейси

* [Отримання деталей документа платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-document-detail)
* [Отримання деталей API платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-api-detail)


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