> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/fr/reference/environment-variables.md). # Variables d'environnement Voici la liste de référence. Chaque variable ci-dessous est lue quelque part dans le code (`process.env.*` côté serveur, `import.meta.env.*` dans le bundle du navigateur). Tout ce qui n'est pas répertorié ici est ignoré. Copier `.env.example` vers `.env` pour commencer : {% code title="shell" %} ```bash cp .env.example .env ``` {% endcode %} `dotenv` charge `.env` depuis la racine du dépôt dans `backend-server.js`, `frontend-server.js`, `common/logger.js`, `sentry-instrument.js`et `vite.config.js`. ## Compilation vs exécution MyIP a deux types de variables, et les confondre est l'erreur de déploiement la plus fréquente. | Type | Préfixe | Lu par | Quand elle prend effet | | ----------- | ------------ | ---------------------------------------------------------------------------------- | ---------------------------------- | | Exécution | sans préfixe | Processus Node.js (`backend-server.js`, `frontend-server.js`, gestionnaires d'API) | Au redémarrage du processus | | Compilation | `VITE_` | Vite, pendant `pnpm run build` | Uniquement après une recompilation | `VITE_*` les valeurs sont **intégrées en dur dans le bundle JavaScript** par Vite au moment de la compilation. Elles ne sont pas lues depuis l'environnement lorsque l'application s'exécute dans le navigateur. Modifier une `VITE_*` variable et redémarrer le serveur ne change rien — il faut recompiler. {% hint style="warning" %} **Conséquence pour Docker.** L'image officielle `jason5ng32/myip:latest` s'exécute `pnpm run build` au moment de la construction de l'image sans `.env` présent (`.env` est listé dans `.dockerignore`). Passer `-e VITE_CURL_IPV4_DOMAIN=...` à cette image n'a **aucun effet sur le bundle frontend**. Pour utiliser des variables de compilation dans Docker, vous devez construire votre propre image avec les valeurs présentes au moment de la compilation. {% endhint %} ## Toutes les variables en un coup d'œil Cliquez sur le nom d'une variable pour accéder à sa description complète. | Variable | Valeur par défaut | Portée | Requis | | ------------------------------------------------------------------------- | ----------------- | ----------------------- | --------------------------- | | [MAXMIND\_ACCOUNT\_ID](#maxmind-account-id) | `""` | Exécution | Fonctionnalités MaxMind | | [MAXMIND\_LICENSE\_KEY](#maxmind-license-key) | `""` | Exécution | Fonctionnalités MaxMind | | [MAXMIND\_AUTO\_UPDATE](#maxmind-auto-update) | `"false"` | Exécution | — | | [CAIDA\_AUTO\_UPDATE](#caida-auto-update) | `"false"` | Exécution | — | | [BACKEND\_PORT](#backend-port) | `11966` | Exécution | — | | [FRONTEND\_PORT](#frontend-port) | `18966` | Exécution | — | | [ALLOWED\_DOMAINS](#allowed-domains) | `""` | Exécution | Déploiements hors localhost | | [SECURITY\_RATE\_LIMIT](#security-rate-limit) | `0` | Exécution | — | | [SECURITY\_DELAY\_AFTER](#security-delay-after) | `0` | Exécution | — | | [SECURITY\_BLACKLIST\_LOG\_FILE\_PATH](#security-blacklist-log-file-path) | `""` | Exécution | — | | [LOG\_LEVEL](#log-level) | `"info"` | Exécution | — | | [LOG\_FORMAT](#log-format) | pretty | Exécution | — | | [LOG\_HTTP](#log-http) | `"false"` | Exécution | — | | [VITE\_SENTRY\_DSN\_FRONTEND](#vite-sentry-dsn-frontend) | `""` | Compilation + exécution | — | | [SENTRY\_DSN\_BACKEND](#sentry-dsn-backend) | `""` | Exécution | — | | [SENTRY\_ENVIRONMENT](#sentry-environment) | `"production"` | Exécution + compilation | — | | [SENTRY\_ORG](#sentry-org) | `""` | Compilation | — | | [SENTRY\_PROJECT\_FRONTEND](#sentry-project-frontend) | `""` | Compilation | — | | [SENTRY\_AUTH\_TOKEN](#sentry-auth-token) | `""` | Compilation | — | | [GOOGLE\_MAP\_API\_KEY](#google-map-api-key) | `""` | Exécution | — | | [IPINFO\_API\_KEY](#ipinfo-api-key) | `""` | Exécution | — | | [IPAPIIS\_API\_KEY](#ipapiis-api-key) | `""` | Exécution | — | | [IP2LOCATION\_API\_KEY](#ip2location-api-key) | `""` | Exécution | — | | [CLOUDFLARE\_API\_KEY](#cloudflare-api-key) | `""` | Exécution | Partage de rapports | | [MAC\_LOOKUP\_API\_KEY](#mac-lookup-api-key) | `""` | Exécution | — | | [RIPESTAT\_SOURCE\_APP](#ripestat-source-app) | `"myip"` | Exécution | — | | [CLOUDFLARE\_ACCOUNT\_ID](#cloudflare-account-id) | `""` | Exécution | Partage de rapports | | [CLOUDFLARE\_KV\_NAMESPACE\_ID](#cloudflare-kv-namespace-id) | `""` | Exécution | Partage de rapports | | [VITE\_CURL\_IPV4\_DOMAIN](#vite-curl-ipv4-domain) | `""` | Compilation | Les trois ou aucun | | [VITE\_CURL\_IPV6\_DOMAIN](#vite-curl-ipv6-domain) | `""` | Compilation | Les trois ou aucun | | [VITE\_CURL\_IPV64\_DOMAIN](#vite-curl-ipv64-domain) | `""` | Compilation | Les trois ou aucun | | [VITE\_SITE\_URL](#vite-site-url) | `""` | Compilation + exécution | — | | [VITE\_DOCS\_URL](#vite-docs-url) | `""` | Compilation | — | | [VITE\_GOOGLE\_ANALYTICS\_ID](#vite-google-analytics-id) | `""` | Compilation | — | | [VITE\_INVISIBILITY\_TEST\_KEY](#vite-invisibility-test-key) | `""` | Compilation | — | | [IPCHECKING\_API\_KEY](#ipchecking-api-key) | `""` | Exécution | — | | [IPCHECKING\_API\_ENDPOINT](#ipchecking-api-endpoint) | `""` | Exécution | — | ## Obligatoire — MaxMind et jeux de données hors ligne La source de géolocalisation IP de MyIP et les badges de pays dans toute l'interface sont servis depuis des bases de données locales MaxMind GeoLite2. Sans elles, `GET /api/maxmind` répond **503**. Voir [Configuration MaxMind](/developer/fr/getting-started/maxmind-setup.md). #### `MAXMIND_ACCOUNT_ID` Valeur par défaut `""` · Exécution · **Requis pour les fonctionnalités MaxMind** ID de compte MaxMind. Associé à `MAXMIND_LICENSE_KEY` en tant qu'identifiants HTTP Basic lors du téléchargement des bases de données GeoLite2. #### `MAXMIND_LICENSE_KEY` Valeur par défaut `""` · Exécution · **Requis pour les fonctionnalités MaxMind** Clé de licence MaxMind, générée depuis la page « Gérer les clés de licence » de votre compte. #### `MAXMIND_AUTO_UPDATE` Valeur par défaut `"false"` · Exécution · Facultatif `"true"` active le système de mise à jour périodique : première vérification 60 secondes après le démarrage, puis toutes les 24 heures. #### `CAIDA_AUTO_UPDATE` Valeur par défaut `"false"` · Exécution · Facultatif `"true"` actualise les jeux de données CAIDA toutes les 24 heures — as2org pour les noms d'organisation ASN, as-rel2 pour le graphe de connectivité ASN. {% hint style="info" %} `MAXMIND_AUTO_UPDATE` contrôle **uniquement le planificateur périodique**. Le chemin de démarrage « télécharger les bases de données si elles manquent » ne le consulte pas — si des identifiants valides sont présents, les bases de données sont récupérées au premier démarrage quoi qu'il arrive (avec un timeout plafonné à 5 minutes). De même, `CAIDA_AUTO_UPDATE=false` permet toujours de télécharger au démarrage les instantanés CAIDA manquants ; cela désactive seulement l'actualisation quotidienne. {% endhint %} Le backend ne refuse jamais de démarrer en raison de bases de données manquantes. Il consigne un avertissement et écoute quand même. ## Ports #### `BACKEND_PORT` Valeur par défaut `11966` · Exécution · Facultatif Port auquel le serveur API Express se lie. Utilisé aussi comme cible de proxy par `frontend-server.js` et par le `/api` proxy du serveur de développement Vite. #### `FRONTEND_PORT` Valeur par défaut `18966` · Exécution · Facultatif Port auquel le serveur statique/SPA se lie en production, et port du serveur de développement Vite en développement. Les deux sont analysés avec `parseInt(..., 10)`. Le Dockerfile `EXPOSE`s `18966` uniquement ; le port du backend reste interne au conteneur. ## Sécurité Voir [Options de sécurité](/developer/fr/configuration/security-options.md) et [Proxy inverse et domaines](/developer/fr/getting-started/reverse-proxy-and-domains.md). #### `ALLOWED_DOMAINS` Valeur par défaut `""` · Exécution · **Effectivement requis pour les déploiements hors localhost** Liste d'hôtes autorisés, séparés par des virgules, pour le global `Referer` de contrôle sur `/api/*`. `localhost` est toujours autorisé ; tout le reste doit être listé ici, sinon chaque appel API depuis votre domaine renvoie un 403. #### `SECURITY_RATE_LIMIT` Valeur par défaut `0` (désactivé) · Exécution · Facultatif Maximum `/api/*` requêtes par adresse IP cliente et par **fenêtre de 20 minutes** de fenêtre. Au-delà de la limite → `429 {"message":"Trop de requêtes"}`. `0` ou non défini désactive complètement le limiteur. #### `SECURITY_DELAY_AFTER` Valeur par défaut `0` (désactivé) · Exécution · Facultatif Après ce nombre de `/api/*` requêtes depuis une même IP dans une **fenêtre de 60 minutes** fenêtre, chaque requête supplémentaire est retardée de `hits × 400 ms`. `0` ou non défini le désactive. #### `SECURITY_BLACKLIST_LOG_FILE_PATH` Valeur par défaut `""` · Exécution · Facultatif Journal sur disque facultatif des IP soumises au rate limiting, par ex. `"logs/blacklist-ip.log"`, résolu relativement à la racine du dépôt. Vide signifie qu'aucun fichier n'est écrit ; le `IP soumise au rate limiting` avertissement est consigné dans tous les cas. Notes de comportement, directement tirées du code : * **La correspondance du Referer se fait par nom d'hôte exact.** `ALLOWED_DOMAINS=example.com` ne **pas** autorise `sub.example.com` — listez chaque nom d'hôte depuis lequel vous servez. * Une requête sans **aucun** `Referer` en-tête est rejetée avec `403 {"error":"Que faites-vous ?"}`. Une requête avec un `Referer` reçoit `403 {"error":"Accès refusé"}`. * Les deux limiteurs **ignorent** `/api/monitoring`; le tunnel Sentry a son propre limiteur fixe (600 requêtes par 20 minutes et par IP). * Le limiteur de requêtes consigne uniquement la transition vers l'état limité, pas chaque requête bloquée. * `app.set('trust proxy', 1)` est défini, donc placez exactement un proxy de confiance devant. L'adresse IP cliente est résolue à partir de `cf-connecting-ip`, puis `x-forwarded-for` (première entrée), puis `cf-connecting-ipv6`, puis l'adresse socket. ## Journalisation Voir [Journalisation](/developer/fr/configuration/logging.md). #### `LOG_LEVEL` Valeur par défaut `"info"` · Exécution · Facultatif Niveau minimal de pino : `debug` / `info` / `warn` / `error`. Les messages de niveau inférieur sont ignorés — y compris leur duplication vers Sentry. #### `LOG_FORMAT` Par défaut pretty · Exécution · Facultatif `"json"` émet un événement JSON par ligne pour les collecteurs de journaux. Toute autre valeur (ou absence de valeur) utilise la sortie colorée `pino-pretty` . #### `LOG_HTTP` Valeur par défaut `"false"` · Exécution · Facultatif `"true"` monte `pino-http` sur `/api/*` : une ligne par requête avec la méthode, l'URL et le statut. Monté avant le limiteur de requêtes, donc les 429 sont aussi consignés. ## Sentry Tous facultatifs. Sans DSN défini, aucun SDK Sentry n'est chargé et aucun code Sentry n'est inclus dans le bundle. Voir [Surveillance des erreurs (Sentry)](/developer/fr/configuration/error-monitoring.md). #### `VITE_SENTRY_DSN_FRONTEND` Valeur par défaut `""` · Compilation **et** exécution · Facultatif DSN frontend, intégré dans le bundle au moment de la compilation. **Aussi lu à l'exécution** par `backend-server.js` — `POST /api/monitoring` (le tunnel d'enveloppe first-party) n'est monté que lorsque cela est défini sur le processus serveur. #### `SENTRY_DSN_BACKEND` Valeur par défaut `""` · Exécution · Facultatif DSN backend, lu par `sentry-instrument.js` (chargé via `node --import`) et par `common/logger.js`, qui duplique `warn+` les lignes vers les journaux Sentry et fait passer `error+` aux tickets. #### `SENTRY_ENVIRONMENT` Valeur par défaut `"production"` · Exécution + compilation · Facultatif Balise d'environnement sur les événements Sentry du backend. Contrôle aussi l'envoi des source maps : l'envoi ne s'exécute que lorsque cette valeur est absente ou `production`. #### `SENTRY_ORG` Valeur par défaut `""` · Compilation · Facultatif Identifiant d'organisation Sentry pour l'envoi des source maps au moment de la compilation. #### `SENTRY_PROJECT_FRONTEND` Valeur par défaut `""` · Compilation · Facultatif Identifiant de projet Sentry pour l'envoi des source maps au moment de la compilation. #### `SENTRY_AUTH_TOKEN` Valeur par défaut `""` · Compilation · Facultatif Jeton d'authentification pour l'envoi des source maps au moment de la compilation. Lorsqu'il n'est pas défini, Vite ne génère pas du tout de source maps, donc elles ne sont jamais servies publiquement depuis `dist/`. Secret de compilation — jamais exposé au navigateur. {% hint style="warning" %} Si vous construisez vous-même une image Docker avec `VITE_SENTRY_DSN_FRONTEND` intégré, transmettez aussi la même valeur au conteneur à l'exécution. Sinon, le bundle envoie les enveloppes vers `/api/monitoring`, une route que le backend n'a jamais montée, et chaque rapport renvoie une 404. {% endhint %} ## Clés API facultatives Chaque clé déverrouille une source de données IP ou un outil. `GET /api/configs` indique lesquels sont définis — uniquement sous forme de booléens, jamais les valeurs — et le frontend masque l'interface correspondante lorsqu'une clé manque. Voir [Clés API facultatives](/developer/fr/configuration/optional-api-keys.md) et [Sources de données IP](/developer/fr/architecture/ip-data-sources.md). #### `GOOGLE_MAP_API_KEY` Valeur par défaut `""` · Exécution · Facultatif Clé Google Static Maps, utilisée par `/api/map`. Accepte une liste séparée par des virgules ; une clé est choisie aléatoirement par requête. #### `IPINFO_API_KEY` Valeur par défaut `""` · Exécution · Facultatif Jeton ipinfo.io pour `/api/ipinfo`. Liste séparée par des virgules prise en charge. Le point de terminaison fonctionne toujours sans clé, au taux anonyme d'ipinfo.io. #### `IPAPIIS_API_KEY` Valeur par défaut `""` · Exécution · Facultatif Clé api.ipapi.is pour `/api/ipapiis`. Liste séparée par des virgules prise en charge. #### `IP2LOCATION_API_KEY` Valeur par défaut `""` · Exécution · Facultatif Clé ip2location.io pour `/api/ip2location`. Liste séparée par des virgules prise en charge. #### `CLOUDFLARE_API_KEY` Valeur par défaut `""` · Exécution · **Requis pour le partage de rapports** Jeton API Cloudflare avec deux rôles : jeton Bearer pour Cloudflare Radar (`/api/cfradar`), et — avec les deux variables dans [Partage de rapports](#report-sharing-cloudflare-kv) — l'identifiant d'accès pour stocker les rapports partageables dans Workers KV. Le rôle KV nécessite en plus la **Workers KV Storage : modification** autorisation sur le jeton. #### `MAC_LOOKUP_API_KEY` Valeur par défaut `""` · Exécution · Facultatif Clé maclookup.app pour `/api/macchecker`. Le point de terminaison fonctionne sans elle, au taux anonyme. #### `RIPESTAT_SOURCE_APP` Valeur par défaut `"myip"` · Exécution · Facultatif Valeur envoyée comme `sourceapp` paramètre de requête, afin que RIPE puisse attribuer le trafic à votre déploiement. {% hint style="info" %} `/api/ipapiis` et `/api/ip2location` construisent leur URL amont en appelant `.split(',')` sur la clé sans vérifier la nullité. Lorsque la clé n'est pas définie, le gestionnaire lève une exception et renvoie 500. Le frontend ne les appelle jamais dans cet état, car `/api/configs` indique que la source est indisponible et l'interface la masque. {% endhint %} ## Partage de rapports (Cloudflare KV) Les rapports de diagnostic partageables sont stockés dans Cloudflare Workers KV via l'API REST. **Les trois** variables — [`CLOUDFLARE_API_KEY`](#cloudflare-api-key) plus les deux ci-dessous — doivent être définies, sinon `POST /api/report` et `GET /api/report/:id` répondent tous deux `503 {"error":"Le partage de rapports n'est pas configuré"}` et `/api/configs` rapports `reportSharing: false`, ce qui masque l'interface de partage. #### `CLOUDFLARE_ACCOUNT_ID` Valeur par défaut `""` · Exécution · **Requis pour le partage de rapports** ID de compte Cloudflare qui possède l'espace de noms KV. #### `CLOUDFLARE_KV_NAMESPACE_ID` Valeur par défaut `""` · Exécution · **Requis pour le partage de rapports** L'espace de noms **ID hexadécimal** du tableau de bord — pas son nom d'affichage. Contraintes du rapport, à partir de `common/report-schema.js`: la rétention sélectionnable est de 1, 3 ou 7 jours (tout autre choix est ramené à 1 jour), et la charge utile stockée est plafonnée à 256 KB (`413` au-delà). La limite du corps JSON d'Express est de 500 KB, délibérément au-dessus du plafond du rapport. ## API cURL #### `VITE_CURL_IPV4_DOMAIN` Valeur par défaut `""` · Compilation · Les trois ou aucun Nom d'hôte IPv4 uniquement affiché dans la carte API cURL. #### `VITE_CURL_IPV6_DOMAIN` Valeur par défaut `""` · Compilation · Les trois ou aucun Nom d'hôte IPv6 uniquement. #### `VITE_CURL_IPV64_DOMAIN` Valeur par défaut `""` · Compilation · Les trois ou aucun Nom d'hôte double pile. {% hint style="warning" %} La carte API cURL ne s'affiche que lorsque **les trois** sont non vides — `curlDomainsHadSet` dans `frontend/store.js` les combine avec un ET logique. En n'en définissant qu'un ou deux, rien n'apparaît. Et comme il s'agit de `VITE_*`variables, elles doivent être présentes au moment de la compilation. {% endhint %} Ces variables ne fournissent que les noms d'hôte affichés aux utilisateurs. MyIP ne sert pas lui-même ces points de terminaison — vous pointez les enregistrements DNS vers n'importe quel service d'écho d'adresse IP en texte brut que vous exécutez. ## Divers #### `VITE_SITE_URL` Valeur par défaut `""` · Compilation **et** exécution · Facultatif L'origine absolue de votre déploiement. Au moment de la compilation, cela renseigne `__SITE_URL__` dans `index.html` (balises canoniques / OG) ; lorsqu'il est vide, tout ce bloc balisé est supprimé. À l'exécution, il devient le dernier segment du `User-Agent` (`MyIP/v7.2.0/https://example.com`), afin que les forks s'identifient auprès des API amont au lieu d'usurper ipcheck.ing. Les barres obliques finales sont supprimées. #### `VITE_DOCS_URL` Valeur par défaut `""` · Compilation · Facultatif Origine du site de documentation GitBook qui alimente l'assistant de documentation intégré à l'application et le lien du Centre d'aide dans le pied de page, par ex. `https://docs.ipcheck.ing`. Les barres obliques finales sont supprimées ; le script d'intégration est chargé depuis `/~gitbook/embed/script.js` lors de la première utilisation, jamais au chargement de la page. Lorsqu'il est vide, ni l'assistant ni le lien du pied de page ne sont intégrés au bundle du tout. Le point d'entrée de navigation exige en plus le déploiement canonique — voir [Fonctionnalités liées à IPCheck.ing](/developer/fr/configuration/features-tied-to-ipcheck-ing.md). #### `VITE_GOOGLE_ANALYTICS_ID` Valeur par défaut `""` · Compilation · Facultatif ID de mesure Google Analytics. Lorsqu'il est vide, `gtag.js` n'est jamais injecté et la page de confidentialité indique que l'analyse est désactivée. Les auto-hébergeurs devraient le laisser vide. #### `VITE_INVISIBILITY_TEST_KEY` Valeur par défaut `""` · Compilation · Facultatif Clé transmise en tant que `pdKey` au script tiers de détection de proxy utilisé par le test d'invisibilité. Cela n'a de sens que sur les déploiements qui disposent aussi de `IPCHECKING_API_KEY`. Non présent dans `.env.example`. #### `IPCHECKING_API_KEY` Valeur par défaut `""` · Exécution · Facultatif Clé API pour l'API compagnon privée d'IPCheck.ing. Contrôle `/api/ipchecking`, `/api/getuserinfo`, `PUT /api/updateuserachievement`, `/api/invisibility`et `/api/dnsleaktest/session/:token` — sans elle, ces routes renvoient `500 {"error":"API key is missing"}`. Également exposé sous `ipChecking` dans `/api/configs`. Pas dans `.env.example`. #### `IPCHECKING_API_ENDPOINT` Valeur par défaut `""` · Exécution · Facultatif URL de base de cette API compagnon, utilisée avec `IPCHECKING_API_KEY`. Pas dans `.env.example`. {% hint style="info" %} `IPCHECKING_API_KEY` / `IPCHECKING_API_ENDPOINT` et `VITE_INVISIBILITY_TEST_KEY` appartiennent à un service compagnon propriétaire. Les forks auto-hébergés ne peuvent pas les obtenir, et les fonctionnalités qu'elles contrôlent sont masquées sur les déploiements non-`ipcheck.ing` ipcheck.ing de toute façon. Voir [Fonctionnalités liées à IPCheck.ing](/developer/fr/configuration/features-tied-to-ipcheck-ing.md). {% endhint %} ## Alias hérités Deux variables ont été renommées. Les anciens noms sont encore lus comme valeurs de repli afin que les déploiements existants ne perdent pas de fonctionnalités lors de la mise à niveau. Préférez les nouveaux noms. | Ancien nom | Nom actuel | Lire où | | ------------------ | -------------------- | ---------------------------------------------------------- | | `IPINFO_API_TOKEN` | `IPINFO_API_KEY` | `api/ipinfo-io.js`, `api/configs.js` | | `CLOUDFLARE_API` | `CLOUDFLARE_API_KEY` | `api/cf-radar.js`, `api/share-report.js`, `api/configs.js` | L'ordre de résolution est `NEW || OLD` — si les deux sont définis, le nouveau nom l'emporte. ## Configuration minimale fonctionnelle {% code title=".env" %} ```bash BACKEND_PORT=11966 FRONTEND_PORT=18966 ALLOWED_DOMAINS="myip.example.com" MAXMIND_ACCOUNT_ID="your-account-id" MAXMIND_LICENSE_KEY="your-license-key" MAXMIND_AUTO_UPDATE="true" ``` {% endcode %} Tout le reste est facultatif et n'ajoute que des sources de données ou des outils. Voir [Démarrage rapide](/developer/fr/getting-started/quickstart.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ipcheck.ing/developer/fr/reference/environment-variables.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.