API Headless (préversion)

Chaque requête porte un header Authorization: Bearer <clé>. La clé est une clé workspace de scope headless:chat, distincte des clés historiques (notify, MCP) : ces dernières sont inertes sur les endpoints headless, même valides par ailleurs.

Une seule clé active à la fois par couple workspace + scope. Préversion privée : il n'existe pas encore d'écran Console dédié au scope headless:chat. Un admin du workspace la génère en appelant POST /api/workspace/{id}/api-key/rotate avec un corps {"scope": "headless:chat"} (session admin requise, même route que la clé MCP legacy, distinguée par ce paramètre). La réponse contient la clé en clair une seule fois, copiez-la immédiatement.

Crée l'utilisateur final s'il n'existe pas encore pour ce workspace, sinon retourne l'existant (find-or-create idempotent). external_user_idest votre identifiant interne (par exemple l'id utilisateur icon), jamais un email ni une donnée sensible.

curl -X POST https://gilbert.solveholding.com/api/headless/v1/users \
  -H "Authorization: Bearer $GILBERT_HEADLESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "icon-user-4821",
    "display_name": "Camille"
  }'

{
  "external_user_id": "icon-user-4821",
  "created": true
}

Champs : external_user_id (string, requis, 1 à 256 caractères), display_name (string, optionnel). 400 si external_user_id est vide, manquant ou dépasse 256 caractères.

Il n'est pas nécessaire d'appeler cet endpoint avant /chat : le premier message d'un external_user_idinconnu crée l'utilisateur au passage. Un appel explicite reste utile pour provisionner un compte en avance ou récupérer created: falsecomme sonde d'existence.

Envoie un message au nom d'un utilisateur final et retourne un stream application/x-ndjson, une ligne JSON par event. Le vocabulaire d'events reprend celui de l'API standard (text-delta, tool-call, tool-result, finish) et en ajoute deux, documentés plus bas : structured_output et error.

curl -N -X POST https://gilbert.solveholding.com/api/headless/v1/chat \
  -H "Authorization: Bearer $GILBERT_HEADLESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "icon-user-4821",
    "message": "Quels evenements as-tu retenus de mes preferences ?"
  }'

{"type":"text-delta","text":"Tu"}
{"type":"text-delta","text":" as"}
{"type":"text-delta","text":" aime"}
{"type":"text-delta","text":" les afterworks tech a Lyon."}
{"type":"finish","finishReason":"stop","usage":{"inputTokens":210,"outputTokens":18}}

Champs : external_user_id (string, requis), message (string, requis, 1 à 32 000 caractères), output_schema (objet, optionnel, voir ci-dessous). 400 si message est vide ; 400 ou 413 au-delà de 32 000 caractères.

La mémoire de l'utilisateur final est activée par défaut : Gilbert retient les préférences et faits marquants entre deux appels, comme en mode personnel.

Marque blanche.Dans ses réponses, l'assistant se présente sous le nom d'assistant configuré pour le workspace (workspaces.assistant_name, par défaut « Gilbert »), pas sous « Gilbert » en dur. Un intégrateur comme Meety expose ainsi l'API sous sa propre marque.

Sortie structurée · output_schema

Fournissez un JSON Schema d'objet (type: object, properties) pour forcer Gilbert à répondre avec des données exploitables directement, sans parsing de prose. C'est le mode conseillé pour recréer un événement externe (Meetup, Eventbrite, etc.) sous forme de champs structurés.

curl -N -X POST https://gilbert.solveholding.com/api/headless/v1/chat \
  -H "Authorization: Bearer $GILBERT_HEADLESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "icon-user-4821",
    "message": "Recree cet evenement : https://www.meetup.com/lyon-tech/events/12345",
    "output_schema": {
      "type": "object",
      "properties": {
        "titre": { "type": "string" },
        "description": { "type": "string" },
        "date": { "type": "string" },
        "heure": { "type": "string" },
        "en_ligne": { "type": "boolean" },
        "adresse": { "type": "string" },
        "photo": { "type": "string" }
      },
      "required": ["titre", "date", "heure", "en_ligne"]
    }
  }'

{"type":"text-delta","text":"..."}
{"type":"tool-call","toolName":"fetch_url","toolCallId":"call_abc","input":{"url":"https://www.meetup.com/lyon-tech/events/12345"}}
{"type":"tool-result","toolCallId":"call_abc","output":"..."}
{"type":"structured_output","data":{
  "titre": "Afterwork Tech Lyon",
  "description": "Rencontre mensuelle des developpeurs lyonnais.",
  "date": "2026-08-14",
  "heure": "19:00",
  "en_ligne": false,
  "adresse": "12 rue de la Republique, 69002 Lyon",
  "photo": "https://meetup.com/photos/xyz.jpg"
}}
{"type":"finish","finishReason":"stop","usage":{"inputTokens":640,"outputTokens":112}}

Le stream se termine par un event {"type":"structured_output","data":{...}} avant le finish. output_schema invalide (pas un objet, pas de properties) : 400immédiat, avant tout appel modèle. Si la sortie du modèle ne respecte pas le schéma, Gilbert retente une fois avec l'erreur de validation renvoyée au modèle ; en cas de deuxième échec, un event error de code structured_output_invalid clôt le stream (voir la section erreurs ci-dessous).

Liste les souvenirs persistants d'un utilisateur final, les plus récents en premier, jusqu'à 100 entrées. Le contenu est déchiffré côté serveur avant retour : aucune clé de chiffrement ne transite côté client.

curl https://gilbert.solveholding.com/api/headless/v1/memory?external_user_id=icon-user-4821 \
  -H "Authorization: Bearer $GILBERT_HEADLESS_KEY"

{
  "memories": [
    {
      "id": "6f1e...c92a",
      "kind": "preference",
      "content": "Aime les afterworks tech a Lyon.",
      "created_at": "2026-07-10T18:22:00Z"
    }
  ]
}

404, code end_user_not_found, si external_user_idn'existe pas pour ce workspace. La lecture est strictement scopée à cet utilisateur : aucune fuite cross-utilisateur possible, même en cas d'erreur côté appelant.

Cet endpoint sert aussi d'export : il n'existe pas d'endpoint d'export dédié en v1, GET memory couvre ce besoin.

Supprime définitivement un utilisateur final : sa mémoire, ses messages et ses sessions sont purgés en cascade. Opération irréversible, à utiliser pour honorer un droit à l'oubli ou nettoyer un compte de test.

curl -X DELETE "https://gilbert.solveholding.com/api/headless/v1/users?external_user_id=icon-user-4821" \
  -H "Authorization: Bearer $GILBERT_HEADLESS_KEY"

{
  "deleted": true
}

404, code end_user_not_found, si l'utilisateur n'existe pas déjà. Sinon {"deleted": true}.

• 5 000 utilisateurs finaux maximum par workspace.
• 100 créations d'utilisateurs finaux par heure et par workspace.
• 32 000 caractères maximum par message.
• 256 caractères maximum pour external_user_id.

Au-delà du plafond d'utilisateurs : 403, code end_user_cap_reached. Au-delà du rythme de création : 429, code end_user_creation_rate_limited.

Deux familles bien distinctes : les codes HTTP classiques (avant que le stream ne démarre) et les events errorà l'intérieur du flux NDJSON de /chat, une fois les en-têtes déjà envoyés en 200.

Codes HTTP

Events d'erreur dans le stream /chat

Une fois le stream /chat démarré, la réponse HTTP est déjà à 200: une erreur survenant en cours de route n'a pas de code HTTP à elle, elle arrive comme une ligne NDJSON de type error, qui clôt le stream.

{"type":"error","code":"workspace_llm_unavailable","message":"La cle LLM du workspace est invalide ou indisponible."}

workspace_llm_unavailable: le workspace a sa propre clé de fournisseur LLM (BYOLLM) et le repli vers la clé centrale Gilbert est désactivé pour ce workspace ; l'appel échoue de façon explicite plutôt que de basculer silencieusement sur une clé qui n'est pas la vôtre.

{"type":"error","code":"structured_output_invalid","message":"La sortie ne correspond pas au schema fourni apres relance."}

structured_output_invalid : après une relance, la sortie du modèle ne respecte toujours pas output_schema. Pas de deuxième retry automatique côté serveur.