# Contenus de l'application

> Configuration au démarrage, thèmes CSS, langues, traductions, traduction par IA et fichiers de branding de votre application.

Ces endpoints fournissent à votre front tout ce qui l'habille : son thème, ses langues, ses textes traduits et ses visuels. Le front les lit au démarrage ; l'équipe qui édite l'application les alimente, depuis la console ou par l'API.

## Lire la configuration de démarrage

::endpoint{method="GET" path="/api/apps/{appWid}/runtime-config"}

**Accès** : tout appelant authentifié, sur **sa propre** application. Renvoie en un appel le thème par défaut, les langues et les visuels de l'application.

```bash
curl -s https://api.wakastart.app/api/apps/EXAPP1/runtime-config \
  -H "x-enriched-token: $ENRICHED_TOKEN"
```

**Réponse `200`**

```json
{
  "theme": { "id": "1e2d3c4b-5555-4a69-8b7c-6d5e4f3a2b10", "name": "clair", "cssUrl": "/themes/1e2d3c4b-5555-4a69-8b7c-6d5e4f3a2b10/css" },
  "languages": [
    { "code": "fr", "name": "Français", "isDefault": true, "i18nUrl": "/languages/fr/file?appWid=EXAPP1&fileType=FRONT" },
    { "code": "en", "name": "English", "isDefault": false, "i18nUrl": "/languages/en/file?appWid=EXAPP1&fileType=FRONT" }
  ],
  "branding": {
    "logoLightUrl": "https://mon-app.exemple.fr/assets/logo-clair.svg",
    "logoDarkUrl": null,
    "faviconUrl": null,
    "bgLightUrl": null,
    "bgDarkUrl": null
  }
}
```

| Champ | Description |
|---|---|
| `theme` | Thème par défaut de l'application, sinon le premier associé, sinon `null`. `cssUrl` est relatif à l'URL de base de l'API |
| `languages` | Langues de l'application. Pour charger un fichier de traduction, appelez [Obtenir l'URL d'un fichier de traduction](#obtenir-lurl-dun-fichier-de-traduction) avec le `code` de la langue |
| `branding` | Visuels de l'application ; `null` pour un visuel absent |

**Erreurs** : `403` `Access denied: you can only access the runtime config of your own application`.

## Thèmes

Un thème est un jeu de variables CSS, en mode clair et en mode sombre, au format des thèmes [shadcn/ui](https://ui.shadcn.com). Les thèmes forment un catalogue ; une application en associe un ou plusieurs, dont un par défaut.

### L'objet Thème

| Champ | Type | Description |
|---|---|---|
| `id` | UUID | Identifiant |
| `name` | chaîne (50) | Nom unique |
| `cssPath` | chaîne (255) ou `null` | Chemin du fichier CSS |
| `cssVarsLight`, `cssVarsDark` | objet | Variables CSS par mode : `{ "--primary": "221.2 83.2% 53.3%" }` |
| `variables` | objet ou `null` | Variables libres |
| `createdAt`, `updatedAt` | chaîne ISO 8601 | Dates |

### Lire les thèmes

::endpoint{method="GET" path="/api/themes"}

**Droit requis** : `themes.read`. Paramètres `page` et `limit`. `GET /api/themes/{id}` et `GET /api/themes/name/{name}` lisent un thème avec le même droit.

### Récupérer le CSS d'un thème

::endpoint{method="GET" path="/api/themes/{id}/css"}

**Accès** : tout appelant authentifié. Renvoie la feuille de style, de type `text/css`, avec `Cache-Control: public, max-age=3600`. L'appel demande un jeton : chargez la feuille depuis votre serveur ou avec `fetch`, pas avec une balise `<link>`.

```bash
curl -s https://api.wakastart.app/api/themes/1e2d3c4b-5555-4a69-8b7c-6d5e4f3a2b10/css \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Créer, modifier ou supprimer un thème

::endpoint{method="POST" path="/api/themes"}

::endpoint{method="PUT" path="/api/themes/{id}"}

::endpoint{method="DELETE" path="/api/themes/{id}"}

**Accès** : Administrateur client avec le droit `themes.create`, `themes.update` ou `themes.delete`.

| Champ | Type | Obligatoire (création) | Contraintes |
|---|---|---|---|
| `name` | chaîne | oui | 50 caractères au plus, unique |
| `cssVarsLight`, `cssVarsDark` | objet | non | Variables CSS |
| `cssPath` | chaîne | non | 255 caractères au plus |
| `variables` | objet | non | — |

```bash
curl -s -X POST https://api.wakastart.app/api/themes \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "clinique-bleu",
    "cssVarsLight": { "--primary": "221.2 83.2% 53.3%", "--background": "0 0% 100%" },
    "cssVarsDark": { "--primary": "217.2 91.2% 59.8%", "--background": "222.2 84% 4.9%" }
  }'
```

### Associer un thème à l'application

| Endpoint | Accès | Rôle |
|---|---|---|
| `GET /api/app-themes/app/{appId}` | Authentifié, sur sa propre application | Thèmes de l'application (`appId` : UUID ou WID) |
| `POST /api/app-themes` | Administrateur client | Associer un thème. Corps : `appId` (UUID), `themeId` (UUID), `isDefault` (booléen, facultatif) |
| `PUT /api/app-themes/app/{appId}/theme/{themeId}/default` | Administrateur client | Définir le thème par défaut |
| `DELETE /api/app-themes/app/{appId}/theme/{themeId}` | Administrateur client | Dissocier un thème. Réponse `204` |

**Erreurs** : `409` `This theme is already added to the app` ; `400` `Cannot remove the default theme. Set another theme as default first.`

## Langues

Le référentiel des langues est commun à toutes les applications. Une application en associe plusieurs, dont une par défaut.

### Lire le référentiel

::endpoint{method="GET" path="/api/languages"}

**Droit requis** : `languages.read`. Paramètres `page` et `limit`. `GET /api/languages/code/{code}` (code ISO : `fr`, `en`) et `GET /api/languages/{id}` lisent une langue.

```json
{ "id": "2f3e4d5c-6666-4b7a-9c8d-7e6f5a4b3c22", "code": "fr", "name": "Français", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }
```

### Obtenir l'URL d'un fichier de traduction

::endpoint{method="GET" path="/api/languages/code/{code}/file"}

**Droit requis** : `languages.read`. Renvoie l'adresse du fichier JSON de traductions publié pour une langue et une application.

| Paramètre | Où | Obligatoire | Description |
|---|---|---|---|
| `code` | chemin | oui | Code de la langue |
| `appWid` | requête | oui | Identifiant court de l'application |
| `fileType` | requête | non | `FRONT` (défaut), `BACK` ou `EXTRA` |

```bash
curl -s "https://api.wakastart.app/api/languages/code/fr/file?appWid=EXAPP1&fileType=FRONT" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

**Réponse `200`**

```json
{ "s3Url": "https://i18n.exemple-stockage.fr/EXAPP1/fr/FRONT.json", "s3Key": "EXAPP1/fr/FRONT.json" }
```

`s3Url` est une adresse publique : chargez-la directement depuis le navigateur. `404` `Translation file not found for app '<appWid>', lang '<code>', type '<fileType>'` si aucun fichier n'est publié.

### Ajouter une langue au référentiel

::endpoint{method="POST" path="/api/languages/find-or-create"}

**Accès** : Administrateur client avec le droit `languages.manage`. Renvoie la langue de ce code si elle existe, sinon la crée. Corps : `code` (10 caractères au plus) et `name` (50 caractères au plus). `POST /api/languages` crée sans rechercher (`409` `Language with code "<code>" already exists`) ; `DELETE /api/languages/{id}` supprime.

### Associer une langue à l'application

| Endpoint | Accès | Rôle |
|---|---|---|
| `GET /api/app-languages/app/{appId}` | Authentifié | Langues de l'application (`appId` : UUID ou WID) |
| `POST /api/app-languages` | Administrateur client | Associer une langue. Corps : `appId` (UUID), `languageId` (UUID), `isDefault` (facultatif) |
| `PUT /api/app-languages/app/{appId}/language/{languageId}/default` | Administrateur client | Définir la langue par défaut |
| `DELETE /api/app-languages/app/{appId}/language/{languageId}` | Administrateur client | Dissocier une langue. Réponse `204` |

Le français et l'anglais sont obligatoires : `400` `La langue <nom> (<code>) est obligatoire et ne peut pas être supprimée`.

## Traductions

Une clé de traduction appartient à une application et à un type de fichier : `FRONT` (votre front), `BACK` (les messages de votre serveur) ou `EXTRA`. Elle a une valeur par langue.

### Lire les traductions

::endpoint{method="GET" path="/api/translations/app/{appId}"}

**Droit requis** : `translations.read`. `appId` : UUID. Paramètre facultatif `fileType` ; sans lui, tous les types.

```bash
curl -s "https://api.wakastart.app/api/translations/app/a1b2c3d4-0000-4000-8000-000000000001?fileType=FRONT" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

**Réponse `200`**

```json
{
  "keys": [
    {
      "id": "4b5c6d7e-8888-4d9e-8f0a-1b2c3d4e5f77",
      "appId": "a1b2c3d4-0000-4000-8000-000000000001",
      "key": "agenda.title",
      "fileType": "FRONT",
      "createdAt": "2026-05-04T08:00:00.000Z",
      "updatedAt": "2026-09-30T15:12:00.000Z"
    }
  ],
  "languages": [{ "id": "2f3e4d5c-6666-4b7a-9c8d-7e6f5a4b3c22", "code": "fr", "name": "Français" }],
  "translations": { "agenda.title": { "fr": "Agenda", "en": "Diary" } }
}
```

| Champ | Description |
|---|---|
| `keys` | Clés de traduction : `id`, `appId`, `key` (255 caractères au plus), `fileType`, `comment` s'il existe, dates |
| `languages` | Langues associées à l'application |
| `translations` | Valeurs, indexées par clé puis par code de langue |

### Créer une clé

::endpoint{method="POST" path="/api/translations/key"}

**Accès** : Administrateur client avec le droit `translations.edit`. Corps : `appId` (UUID), `key` (255 caractères au plus), `fileType` (facultatif), `comment` (facultatif). `409` `Translation key "<clé>" already exists for fileType <type>`.

### Modifier une valeur

::endpoint{method="PUT" path="/api/translations/value"}

**Accès** : Administrateur client avec le droit `translations.edit`. Corps : `keyId` (UUID), `languageId` (UUID), `value` (texte).

### Mettre à jour en masse

::endpoint{method="PUT" path="/api/translations/bulk"}

**Accès** : Administrateur client avec le droit `translations.edit`. Crée les clés absentes et met à jour les valeurs.

| Champ | Type | Obligatoire | Contraintes |
|---|---|---|---|
| `appId` | UUID | oui | Application |
| `translations` | tableau | oui | 1 à 500 éléments `{ key, languageId, value }` |

```bash
curl -s -X PUT https://api.wakastart.app/api/translations/bulk \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "appId": "a1b2c3d4-0000-4000-8000-000000000001",
    "translations": [
      { "key": "agenda.title", "languageId": "2f3e4d5c-6666-4b7a-9c8d-7e6f5a4b3c22", "value": "Agenda" },
      { "key": "agenda.empty", "languageId": "2f3e4d5c-6666-4b7a-9c8d-7e6f5a4b3c22", "value": "Aucun rendez-vous" }
    ]
  }'
```

**Réponse `200`** : `{ "updated": 2 }`, le nombre de valeurs écrites.

### Supprimer une clé

::endpoint{method="DELETE" path="/api/translations/app/{appId}/key/{key}"}

**Accès** : Administrateur client avec le droit `translations.edit`. Paramètre facultatif `fileType`. Réponse `204`.

## Traduction par IA

Ces endpoints remplissent les valeurs vides d'une ou plusieurs langues. Chaque appel consomme des [crédits](/v1.0/reference-api/credits), débités au moment de l'appel. **Accès** : Administrateur client avec le droit `translations.ai`.

| Endpoint | Corps | Opération débitée |
|---|---|---|
| `POST /api/ai-translation/bulk` | `appId` (UUID), `fileType`, `targetLanguageId` (UUID), `sourceLanguageCode` (facultatif, `en` par défaut) | `AI_TRANSLATE_BULK` |
| `POST /api/ai-translation/bulk-multi` | `appId`, `fileType`, `sourceLangId` (UUID), `targetLangIds` (20 UUID au plus) | `AI_TRANSLATE_MULTI` |
| `POST /api/ai-translation/single` | `text` (5 000 caractères au plus), `fromLang`, `toLang` (noms de langue en clair, 50 caractères au plus) | `AI_TRANSLATE_SINGLE` |

```bash
curl -s -X POST https://api.wakastart.app/api/ai-translation/bulk \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "appId": "a1b2c3d4-0000-4000-8000-000000000001",
    "fileType": "FRONT",
    "targetLanguageId": "3a4b5c6d-7777-4c8d-9e0f-1a2b3c4d5e66"
  }'
```

**Réponse `200`** : `{ "translated": 42, "errors": 0 }`, soit le nombre de valeurs traduites et le nombre d'échecs. La traduction vers plusieurs langues renvoie `{ "results": [{ "langId", "translated", "errors" }], "totalTranslated", "totalErrors" }` ; celle d'un texte libre, `{ "translated": "<texte traduit>" }`.

::endpoint{method="GET" path="/api/ai-translation/empty-count/{appId}"}

**Accès** : Administrateur client avec le droit `translations.read`. Paramètres obligatoires `fileType` et `languageId`. Réponse : `{ "total": 120, "empty": 12, "filled": 108 }`, en nombre de clés. Utile pour savoir s'il reste des valeurs à traduire avant de lancer une traduction.

**Erreurs** : `402` `Insufficient credits` ; `400` `Missing customer context` ; `500` `AI translation service unavailable`. Le délai d'attente de ces appels est de 120 secondes.

## Fichiers de branding

::endpoint{method="GET" path="/api/branding/assets/{appWid}/{chemin}"}

**Droit requis** : `branding.read`. Redirige (`302`) vers l'adresse de téléchargement d'un visuel de l'application : logo, fond, favicon ou fichier personnalisé.

| Paramètre | Contraintes |
|---|---|
| `appWid` | Lettres, chiffres, `-` et `_` |
| `chemin` | 1 à 1 023 caractères, sans `..`, `\` ni caractère de contrôle : `logo-light.png` |

```bash
curl -s -o logo.png -L https://api.wakastart.app/api/branding/assets/EXAPP1/logo-light.png \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

**Erreurs** : `400` `appWid invalide`, `key invalide ou manquante`, `key contient des caractères non autorisés`.
