---
title: Lettura & sistema
description: Risorse di sola lettura — utenti, ruoli, log delle call, numeri — ed endpoint di sistema (health, version, api-logs) dell'API REST partner.
---

Questo gruppo raccoglie le risorse **di sola lettura** utili a contestualizzare
le integrazioni (utenti, ruoli, call, numeri) e gli **endpoint di sistema**
(health, version, log delle proprie chiamate API).

## Risorse di sola lettura (GET)

| Path | Descrizione |
|------|-------------|
| `GET /platform-users` | Utenti piattaforma dell'Account |
| `GET /roles` | Ruoli IAM dell'Account |
| `GET /calls` | Log delle call (AI voice) |
| `GET /phone-numbers` | Numeri di telefono configurati |

Tutte richiedono l'header `X-API-Key`. Sono **read-only**: l'API partner non
espone la creazione/modifica di queste entità (si gestiscono dal dashboard).

### Utenti e ruoli

`GET /platform-users` elenca gli utenti dell'Account (paginazione `page`,
`pageSize`, ricerca `search`); `GET /roles` elenca i ruoli IAM. Utili, ad
esempio, per mappare nel tuo sistema gli owner delle entità o per mostrare i
nomi degli operatori.

<Tabs items={["curl", "JavaScript"]}>
<Tab value="curl">

```bash
curl "https://api.audin.ai/platform-users?page=1&pageSize=50" \
  -H "X-API-Key: $API_KEY"
```

</Tab>
<Tab value="JavaScript">

```js
const res = await fetch(
  "https://api.audin.ai/platform-users?page=1&pageSize=50",
  { headers: { "X-API-Key": process.env.AUDIN_API_KEY } },
);
const users = await res.json();
```

</Tab>
</Tabs>

### Call e numeri

`GET /calls` restituisce il log delle chiamate (gestite dai bot AI voice e dagli
operatori umani) (paginazione `page`/`pageSize`, filtri `status`, `search`,
ordinamento `orderBy`/`orderDir`); il dettaglio di una singola call è su
`GET /calls/{id}`.
`GET /phone-numbers` elenca i numeri configurati sull'Account.

<Tabs items={["curl", "JavaScript"]}>
<Tab value="curl">

```bash
# Ultime call, ordinate per data discendente
curl "https://api.audin.ai/calls?page=1&pageSize=20&orderDir=desc" \
  -H "X-API-Key: $API_KEY"

# Numeri configurati
curl "https://api.audin.ai/phone-numbers" \
  -H "X-API-Key: $API_KEY"
```

</Tab>
<Tab value="JavaScript">

```js
const headers = { "X-API-Key": process.env.AUDIN_API_KEY };

const calls = await (
  await fetch(
    "https://api.audin.ai/calls?page=1&pageSize=20&orderDir=desc",
    { headers },
  )
).json();

const phoneNumbers = await (
  await fetch("https://api.audin.ai/phone-numbers", { headers })
).json();
```

</Tab>
</Tabs>

<Callout type="info">
  L'`id` di un numero ottenuto da `GET /phone-numbers` è lo stesso da passare,
  ad esempio, all'endpoint di sessione operatore (`phoneNumberIds`). Schema e
  campi esatti di ogni risorsa: [Swagger](https://api.audin.ai/docs/partners).
</Callout>

## Endpoint di sistema

| Path | Auth | Descrizione |
|------|------|-------------|
| `GET /health` | nessuna | Health check del servizio |
| `GET /version` | nessuna | Versione dell'API |
| `GET /api-logs` | `X-API-Key` | Log delle chiamate effettuate con la tua API Key |

### Health e version

`GET /health` non richiede autenticazione ed è pensato per i probe di
monitoraggio; `GET /version` riporta la versione dell'API.

<Tabs items={["curl", "JavaScript"]}>
<Tab value="curl">

```bash
curl https://api.audin.ai/health
```

</Tab>
<Tab value="JavaScript">

```js
const res = await fetch("https://api.audin.ai/health");
const health = await res.json();
```

</Tab>
</Tabs>

### Log delle chiamate API

`GET /api-logs` espone il log delle richieste effettuate con la **tua** API Key —
utile per audit e debug delle integrazioni. Supporta paginazione (`page`,
`pageSize`) e filtri `method`, `statusGroup`, `path`.

<Tabs items={["curl", "JavaScript"]}>
<Tab value="curl">

```bash
curl "https://api.audin.ai/api-logs?page=1&pageSize=50&method=POST" \
  -H "X-API-Key: $API_KEY"
```

</Tab>
<Tab value="JavaScript">

```js
const params = new URLSearchParams({ page: "1", pageSize: "50", method: "POST" });
const res = await fetch(`https://api.audin.ai/api-logs?${params}`, {
  headers: { "X-API-Key": process.env.AUDIN_API_KEY },
});
const logs = await res.json();
```

</Tab>
</Tabs>

<Callout type="info">
  Schema completo (tutti i campi e parametri):
  [Swagger](https://api.audin.ai/docs/partners).
</Callout>

## Prossimo passo

<Cards>
  <Card href="/docs/api-rest/flussi" title="Flussi operativi" description="Esempi end-to-end che combinano scrittura e lettura delle risorse." />
  <Card href="/docs/api-rest/errori" title="Errori & deprecati" description="Glossario dei codici di errore e endpoint deprecati." />
</Cards>