API de l'assistant

Le widget de ton site appelle une seule route. Tu peux l’appeler toi-même, depuis une page servie par une adresse déclarée dans la console, pour intégrer l’assistant ailleurs.

POST https://docs.hgdc.ch/api/v1/ask
Content-Type: application/json
Origin: https://docs.acme.ch

Requête

{
  "project": "k57a8m2x9q4n1b3c5d7e9f0g2h4j6k8m",
  "question": "Comment publier ma doc ?",
  "page": "/guides/publier/",
  "previous": ["j97f2k8m1q4n6b3c5d7e9f0g2h4j6k8m"]
}

Champ	Obligatoire	Règle
project	oui	Identifiant du projet, 8 à 64 caractères, lettres minuscules et chiffres.
question	oui	Entre 2 et 1 000 caractères, espaces de début et de fin retirés.
page	non	Chemin de la page ouverte, qui commence par /. 512 caractères au plus. Les passages de cette page sont légèrement favorisés.
previous	non	Les id des réponses précédentes de la conversation, 3 au plus.

Le corps de la requête fait 32 Ko au plus.

L’en-tête Origin doit être l’adresse du site ou une des autres adresses déclarées dans Réglages. Sans cet en-tête, ou avec une autre origine, la requête est refusée. Voir Adresse du site et domaines.

Le champ previous

L’assistant relit lui-même ce qu’il a répondu : tu ne fournis pas le texte des réponses précédentes, seulement leurs id. Seules les réponses answered du même projet, datées de moins de deux heures, sont reprises. Un id inconnu ou plus ancien est ignoré sans erreur.

Réponse

{
  "id": "j97f2k8m1q4n6b3c5d7e9f0g2h4j6k8m",
  "status": "answered",
  "answer": "Importe le dépôt dans Host[^1], puis synchronise le projet dans la console[^2].",
  "sources": [
    { "n": 1, "title": "Publier avec Host", "section": "Avec Host", "url": "https://docs.acme.ch/guides/publier/#avec-host" },
    { "n": 2, "title": "Publier avec Host", "section": "Relier la console", "url": "https://docs.acme.ch/guides/publier/#relier-la-console" }
  ]
}

Champ	Contenu
id	Identifiant de la réponse. Transmets-le dans previous pour la question suivante.
status	answered si la doc répond, no_answer sinon.
answer	Markdown simple. [^n] renvoie à la source n.
sources	Les passages réellement cités : n, title, section (ou null), url. Vide quand status vaut no_answer.

Quand status vaut no_answer, answer dit que la doc ne répond pas et propose de reformuler. Une réponse sans source valide est traitée de la même façon.

Erreurs

Chaque erreur a le même format :

{ "error": { "code": "rate_limited", "message": "Trop de questions d'un coup. Réessaie dans une minute." } }

Code HTTP	error.code	Quand
400	invalid_request	Corps illisible, trop volumineux, ou champ hors règle.
404	project_not_found	Identifiant de projet inconnu.
403	assistant_disabled	L’assistant est coupé dans la console.
403	origin_not_allowed	L’origine n’est pas une adresse du projet, ou l’en-tête manque.
409	not_indexed	Le site n’est pas encore indexé.
429	rate_limited	Trop de questions dans la minute, ou pour ce visiteur ou cette doc aujourd’hui. Le message dit quand réessayer.
429	quota_exceeded	Le quota mensuel de l’organisation est atteint.
503	unavailable	Le modèle ne répond pas. Réessaie dans un moment.

Le champ error.message est une phrase en français, à montrer telle quelle à l’utilisateur. Les seuils de chaque limite sont dans Limites.