Cette page t'a-t-elle aidé ?
Cette page t'a-t-elle aidé ?
Référence
Endpoints REST que vous pouvez appeler côté client (cookie Supabase), serveur-à-serveur (JWT SSO) ou via OAuth Gilbert pour la façade workspace. Stream NDJSON pour le chat, multipart pour l'upload.
Dernière mise à jour : 26 septembre 2026
| Endpoint | Auth | Description |
|---|---|---|
| POST /api/chat | session ∨ JWT ∨ guest | Stream NDJSON. Une ligne JSON par delta (text-delta, tool-call, finish). |
| GET /openapi.json | public metadata | Spec OpenAPI 3.1 pour la façade workspace OAuth2. |
| GET /api/gilbert/workspaces | OAuth workspace:read | Liste les workspaces accessibles au token OAuth. |
| GET /api/gilbert/workspaces/:id/routines | OAuth workspace:read | Liste les routines d'un workspace, sans secrets ni prompts internes. |
| POST /api/gilbert/workspaces/:id/search | OAuth workspace:read | Recherche courte dans le contexte workspace non sensible. |
| POST /api/gilbert/routines/:id/run | OAuth workspace:read + routines:run | Déclenche une routine avec identité user explicite. |
| POST /api/gilbert/upload | session | Multipart (champ file), max 4 Mo par fichier. Retourne { file }, dont le champ id se passe dans attachments du prochain message. Un même nom déposé deux fois donne deux fichiers distincts. 413 code files_quota_exceeded, avec used_bytes et quota_bytes, quand l'espace de fichiers (2 Go par personne et par espace) est plein. |
| GET /api/gilbert/files | session | Vos fichiers dans l'espace courant : { files: [{ id, path, mime_type, size_bytes, source, created_at, conversation_count }], usage: { used_bytes, quota_bytes, file_count } }. Avec ?view=recent&limit=N (N de 1 à 10 ; 3 par défaut ou si la valeur est invalide, 10 au-delà de 10), seulement vos N fichiers les plus récents, sans conversation_count, avec le même usage. L'en-tête x-gilbert-workspace-id sélectionne l'espace (à défaut, l'espace courant) ; 403 si vous n'êtes pas, ou plus, membre de cet espace. |
| DELETE /api/gilbert/files | session | Supprime des fichiers. Body { ids } : 1 à 100 identifiants (uuid). L'en-tête x-gilbert-workspace-id sélectionne l'espace (à défaut, l'espace courant) ; 403 si vous n'êtes pas, ou plus, membre de cet espace. Même origine exigée (403 sinon). 400 si le body ou un identifiant est invalide, 403 sans compte connecté, 404 si aucun identifiant ne vous appartient. Réponse { removed_ids, unindex_failed_ids, unindexed_retry_ids, usage }. Si unindex_failed_ids n'est pas vide, la réponse est une 500 de code files_unindex_failed : ces fichiers-là n'ont pas été supprimés et restent dans votre liste, renvoyez les mêmes ids pour réessayer. |
| POST /api/gilbert/embed/test-token | session | Génère un JWT TTL 1h pour preview iframe (admins seulement). |
| POST /api/gilbert/embed/agents | session (admin de l'espace) | Crée un agent embarqué. Champ optionnel workspace_id : l'espace porteur, à défaut votre espace actif. 400 workspace_id_invalid si la valeur n'est pas une chaîne non vide, 403 workspace_forbidden si vous n'êtes pas admin de l'espace retenu. |
| GET /api/gilbert/embed/agents/:slug | session (admin de l'espace) | Fiche d'un agent, sans son secret. 404 pour un non-admin comme pour un slug inconnu. |
| PATCH /api/gilbert/embed/agents/:slug | session (admin de l'espace) | Modifie l'agent, ou fait tourner son secret avec rotate_secret. |
| DELETE /api/gilbert/embed/agents/:slug | session (admin de l'espace) | Supprime l'agent définitivement. Préférer PATCH status: archived pour désactiver. |
Pour les clients qui ne veulent pas piloter le protocole MCP complet, Gilbert expose une petite façade REST décrite par /openapi.json. Elle couvre la découverte workspace, les routines et une recherche safe dans le contexte non sensible.
curl -H "Authorization: Bearer $GILBERT_MCP_ACCESS_TOKEN" \
https://gilbert.solveholding.com/api/gilbert/workspaces
curl -X POST \
-H "Authorization: Bearer $GILBERT_MCP_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query":"routines email"}' \
https://gilbert.solveholding.com/api/gilbert/workspaces/$WORKSPACE_ID/search/api/chat accepte les requêtes sans header Authorization ni cookie Supabase. Dans ce cas Gilbert bascule en mode guest : un cookie de session ephémère est posé côté navigateur (isolé par cookie, donc par navigateur), et la conversation n'est rattachée à aucun utilisateur identifié.
Utile pour les démos, les pages publiques, et les flux de support pre-signup où vous voulez laisser un visiteur poser une question sans créer de compte.
En production avec des utilisateurs identifiés, passez à JWT SSO : la conversation est rattachée au sub et la limite devient par session utilisateur.
POST /api/chat HTTP/1.1
Host: gilbert.solveholding.com
Content-Type: application/json
Cookie: sb-access-token=… # OU
Authorization: Bearer JWT_SSO
{
"message": "Bonjour Gilbert",
"chat_id": null,
"attachments": []
}Le body accepte message (string, requis), chat_id (uuid ou null pour démarrer une nouvelle conv), attachments (array des file.id obtenus via /api/gilbert/upload).
Le serveur renvoie un stream application/x-ndjson : chaque ligne est un objet JSON. Lisez-les au fur et à mesure pour afficher la réponse en streaming.
HTTP/1.1 200 OK
Content-Type: application/x-ndjson; charset=utf-8
Transfer-Encoding: chunked
{"type":"text-delta","text":"Bon"}
{"type":"text-delta","text":"jour"}
{"type":"tool-call","toolName":"send_email","toolCallId":"call_abc","input":{"to":"…"}}
{"type":"tool-result","toolCallId":"call_abc","output":"sent"}
{"type":"finish","finishReason":"stop","usage":{"inputTokens":42,"outputTokens":7}}text-delta : fragment de texte assistant. Concaténer dans l'ordre.tool-call : Gilbert demande l'exécution d'un tool métier. Pour les tools côté votre backend, vous recevrez un webhook en parallèle.tool-result : résultat (succès ou erreur) du tool, avec toolCallId qui matche le tool-call.finish : fin du stream. finishReason ∈ stop · length · tool-calls · error. usage contient les tokens consommés (input + output).curl -N \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $GILBERT_JWT" \
-d '{"message":"Bonjour","chat_id":null}' \
https://gilbert.solveholding.com/api/chatLe flag -N désactive le buffering de cURL pour voir les deltas en temps réel. $GILBERT_JWT est un token signé avec votre secret SSO (voir JWT SSO).
| Code | Sens | Action |
|---|---|---|
| 401 | JWT ou cookie de session fourni mais invalide / expiré. L'absence totale d'auth ne déclenche pas 401 : bascule en mode guest. | Refresh token côté backend, retry |
| 403 | Permissions insuffisantes (tenant_mismatch) | Vérifier le claim iss |
| 413 | Payload trop gros (upload > 4 Mo), ou espace de fichiers plein : code files_quota_exceeded, avec used_bytes et quota_bytes | Compresser ou découper, ou supprimer des fichiers via DELETE /api/gilbert/files |
| 429 | Rate limit dépassé | Backoff selon header Retry-After |
| 5xx | Erreur côté Gilbert | Retry avec backoff côté votre client |
Par défaut sur tous les endpoints :
Les réponses 429 incluent les headers X-RateLimit-Remaining et Retry-After. Pour des limites custom contactez-nous.