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

# Ottenere l'elenco dei documenti della piattaforma AceDataCloud

> Platform API guide - Ace Data Cloud

Restituisce in modo paginato i documenti per sviluppatori visibili nel sito corrente, utilizzabile per la ricerca, l'indicizzazione o la costruzione autonoma della navigazione nel client. L'elenco include attualmente il `content` e le informazioni sul genitore annidato di ciascun documento, e la risposta potrebbe essere grande.

## Panoramica dell'interfaccia

| Voce | Contenuto |
| - | - |
| Metodo | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/documents/` |
| Autenticazione | Pubblica; i non amministratori non possono vedere i documenti private |
| Paginazione | `count` + `items` |

## Parametri di query

| Parametro | Tipo | Obbligatorio | Predefinito | Descrizione |
| - | - | - | - | - |
| `id` | UUID | No | — | Filtra per ID documento; supporta parametri ripetuti |
| `private` | boolean | No | — | Filtra per stato private; i non amministratori non possono comunque vedere i documenti privati |
| `type` | string | No | — | Filtra con corrispondenza esatta in base al valore effettivo `type` di Document |
| `tag` | string | No | — | Filtra per tag |
| `limit` | integer | No | 10 | Numero di elementi per pagina, massimo 100 |
| `offset` | integer | No | 0 | Offset di paginazione |
| `ordering` | string | No | `rank` | Supporta solo l'ordinamento per `rank`; il prefisso `-` indica l'ordine decrescente |

L'attuale interfaccia elenco non supporta il filtraggio per `alias` o `parent_id`. Se l'alias è noto, chiamare direttamente i [dettagli del documento](https://platform.acedata.cloud/documents/platform-document-detail); quando si costruisce la navigazione ad albero, dopo aver recuperato una pagina, raggruppare nel client usando `parent.id` di ciascun elemento.

## Esempio di richiesta

```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"))
```

## Struttura della risposta

```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"
    }
  ]
}
```

L'elenco utilizza `DocumentIndexSerializer` e attualmente restituisce i campi del modello e le relazioni annidate; i documenti API associati possono anche includere `api_method`. I campi potrebbero essere aggiunti in modo retrocompatibile e il client dovrebbe leggerli secondo necessità. Quando sono necessari `children`, la lingua del contenuto analizzato e l'hash del contenuto, utilizzare l'interfaccia dei dettagli.

Per i record pubblici associati a documenti sorgente, `content_source` fornisce l'identificatore del documento sorgente, l'hash del contenuto sorgente, la lingua richiesta, il momento di aggiornamento della traduzione e lo stato `ready`, `stale`, `missing`, `missing_source` o `ambiguous`; per gli altri record questo campo è `null`. L'`content_hash` quando lo stato è `ready` corrisponde alla traduzione in quella lingua. Il corpo viene comunque visualizzato secondo le regole originali, incluso il fallback della lingua quando manca una traduzione; i client che devono sincronizzare i documenti devono controllare sia lo stato sia l'hash e non possono stabilire che sia aggiornato solo perché il corpo non è vuoto.

## Suggerimenti per l'uso

* La risposta contiene il corpo del testo; durante la sincronizzazione in batch utilizzare la paginazione e impostare timeout ragionevoli, non recuperare in parallelo la stessa pagina.
* alias è l'identificatore stabile dell'URL della pagina pubblica; quando l'alias è noto, richiedere direttamente `/api/v1/documents/{alias}`.
* L'interfaccia attuale non consente il filtraggio lato server per genitore; quando si costruisce la navigazione, raggruppare nel client per `parent.id`.

## Interfacce correlate

* [Ottenere i dettagli del documento della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-document-detail)
* [Ottenere i dettagli dell'API della piattaforma AceDataCloud](https://platform.acedata.cloud/documents/platform-api-detail)


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