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

> ## Agent Instructions
> Documentazione di dentalspace. Il testo completo, incluso il riferimento API, è in /llms-full.txt. Per endpoint, campi e codici di errore la fonte di verità è openapi.json: non usare endpoint o campi non documentati.

# Dati clinici e registro accessi

> Gli scope clinical:*, cosa aprono, perché sono spenti di default e come ogni accesso finisce nel registro della clinica.

I dati sanitari dei pazienti hanno scope a parte: `clinical:read` e `clinical:write`. Sono **spenti di default** in ogni chiave e in ogni modello, e ogni accesso viene registrato.

## Come si accendono

Nella finestra **Nuova chiave API**, area **Dati clinici**. L'app mostra un avviso prima di darli. Accenderli accende anche **Pazienti** in lettura: `clinical:read` da solo non apre niente.

Accendili solo se il programma collegato ne ha davvero bisogno. Il modello **Agente vocale** non li comprende mai.

## Cosa aprono

| Endpoint | Senza `clinical:read` | Con `clinical:read` |
| - | - | - |
| `GET /patients/{id}` | Anagrafica | Anche allergie, farmaci, condizioni e note |
| `GET /patients/{id}/clinical` | `403 insufficient_scope` | Allergie, farmaci, condizioni e odontogramma |
| `GET /appointments/{id}` | Senza note | Anche note e note cliniche |
| `GET /treatment-plans/{id}` | Voci e importi | Anche denti, superfici, odontogramma e diagnosi |
| `GET /documents/{id}` | Tipo e stato della firma | Anche il contenuto e la firma |
| `GET /calls/{id}` | La telefonata | Anche la trascrizione |
| `GET /conversations/{id}/messages` | I messaggi | Anche la trascrizione dei vocali, solo per i pazienti |

`clinical:write` serve per scrivere allergie, farmaci, condizioni e note del paziente (`POST /patients`, `PATCH /patients/{id}`), trascrizioni e note cliniche.

Gli elenchi (`GET /patients`, `GET /appointments` e gli altri) non contengono mai dati sanitari, nemmeno con `clinical:read`: si leggono solo nel dettaglio. Anche i [webhook](/api/webhook) non li portano mai.

## Registro accessi

Ogni richiesta autenticata finisce nel registro accessi della clinica: quale chiave, quale endpoint, cosa ha cercato, con che esito. Quando la risposta contiene dati sanitari, il registro segna anche **quali pazienti** sono stati letti.

Finiscono nel registro come accesso a dati sanitari:

* ogni lettura fatta con `clinical:read` che restituisce dati clinici;
* ogni scrittura fatta con `clinical:write`;
* le letture di testo libero che può contenere informazioni sulla salute, anche con uno scope normale: il testo dei messaggi WhatsApp, titolo e motivo degli appuntamenti, il titolo delle attività e dei documenti.

Se il registro non si riesce a scrivere, la risposta è `500 internal_error` e i dati non escono: un dato sanitario senza traccia non lascia mai dentalspace.

Il registro si conserva 24 mesi. Revocare o cancellare una chiave non cancella le sue tracce.

## Documenti

L'API non espone file da scaricare né accetta file da caricare: i documenti da firmare sono testo e firma, non file. `documents:write` oggi non apre nessun endpoint.


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