Aller au contenu principal

← Retour aux docs

Référence API

Pilotez GnamiAI depuis n'importe où.

Une seule clé Bearer, du JSON sur HTTPS, et chaque endpoint qui anime le tableau de bord. Construisez un bot Discord, un miroir intelligent, un cron qui résume votre boîte courriel — même surface que l'app web. Pas de SDK requis ; fetch suffit.

1. Authentification

Chaque endpoint authentifié accepte une clé Bearer dans l'en-tête Authorization : 

Authorization: Bearer gnami_xxxxxxxxxxxxxxxxxxxxxx

Créez-en une dans le tableau de bord à Paramètres → Clés API. La clé complète n'est affichée qu'une seule fois à la création. Nous ne stockons que son haché scrypt — on ne peut pas la récupérer. Si elle est perdue, révoquez-la et créez-en une nouvelle.

Une clé porte la même autorité qu'une session navigateur pour l'espace propriétaire, à quelques exceptions près notées à la section 10.

2. Erreurs et limites de débit

Chaque erreur est un corps JSON avec error (code machine) et message (humain). Le code HTTP suit la sémantique habituelle :

Limite sur /api/agent/turn : 20 tours par minute par espace, peu importe la clé qui les a déclenchés. Le dépassement renvoie 429 + Retry-After: 60. Les autres endpoints ne sont pas limités par appel aujourd'hui ; le plafond budgétaire s'applique au coût d'inférence selon votre plan dans Paramètres.

3. POST /api/agent/turn — piloter l'agent

Le moment principal. Envoie un tour à votre fournisseur configuré, charge vos compétences et votre mémoire, exécute optionnellement les blocs gnami-action émis par le modèle, et retourne la réponse visible pour l'utilisateur.

Corps

{
  "input":      "string, requis, ≤ 8 000 caractères",
  "history":    [{ "role": "user"|"assistant", "content": "..." }, ...],
  "subagentId": "uuid | null",
  "attachments": [{ "name": "doc.pdf", "mimeType": "application/pdf", "data": "<base64>" }],
  "audio_input": "<octets audio base64> (optionnel, déclenche la STT Whisper)"
}

Réponse (200)

{
  "output":    "string — la réponse de l'assistant",
  "provider":  "openai|anthropic|openrouter|ollama",
  "model":     "gpt-4o-mini",
  "latencyMs": 1240,
  "agentName": "default | <nom du sous-agent>",
  "actions":   [{ "type": "create_skill", "ok": true, "summary": "..." }],
  "context":   { "memoriesUsed": 0, "skillsUsed": 2, "historyMessages": 4, ... }
}

curl

curl https://gnamiai.live/api/agent/turn \
  -H "Authorization: Bearer $GNAMI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Résume ma semaine."}'

Node

const res = await fetch("https://gnamiai.live/api/agent/turn", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GNAMI_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ input: "Résume ma semaine." })
});
const { output } = await res.json();
console.log(output);

4. /api/skills — compétences de l'espace

Blocs Markdown injectés dans le prompt système au moment du tour quand enabled = true.

Quotas : voir Paramètres → Compte, dépend de votre plan.

5. /api/subagents — spécialisations gérées

Personas nommés avec leur propre prompt système et un modèle optionnel. Épinglez-en un dans le clavardage avec /agent <nom> ou passez subagentId à /api/agent/turn.

6. /api/crons — exécutions planifiées

Tours d'agent récurrents. Déclenchés par Vercel Cron à la cadence définie par interval_minutes. L'agent ramasse chaque cron dont next_run_at ≤ now().

7. /api/approvals — portes HITL en attente

Actions destructrices que l'agent a émises mais ne peut pas exécuter sans votre validation. Construisez une UI d'approbation custom en interrogeant ?status=pending.

8. /api/memory/tree — épisodes et mémoire long terme

Épisodes de conversation (résumés auto-générés de 2-3 phrases, 50 plus récents) plus le statut de connexion Mem0 si configuré. 

GET /api/memory/tree
→ {
  "episodes": [{ "id", "ts", "summary", "tokens" }, ...],
  "mem0":     { "connected": true|false, "scope": "..." }
}

9. Endpoints marketplace publics (sans auth)

N'importe qui peut les appeler — utile pour des indexeurs, des intégrations, ou un miroir du marketplace. Pas d'en-tête Bearer nécessaire.

10. Endpoints inaccessibles aux clés API

Ceux-ci retournent 401 en auth Bearer même avec une clé valide — ils nécessitent une vraie session navigateur. L'intention est d'empêcher une clé fuitée de pouvoir détruire l'espace ou s'auto-élever.

11. Recettes de bout en bout

Quatre scripts Node prêts à l'emploi. Affichage ou téléchargement direct — ce sont des fichiers .mjs servis par le site :

Chacun fait moins de 100 lignes et tourne avec node script.mjs + la variable d'env GNAMI_KEY. Récupération rapide : 

curl -O https://gnamiai.live/examples/agent-turn.mjs
export GNAMI_KEY=gnami_xxxxxxxxxxxxxxxxxxxxxx
node agent-turn.mjs "ping"

Ou lisez le README pour la configuration complète.

Construire l'intégration

Créez une clé dans Paramètres, copiez un des scripts d'exemple, changez trois lignes. Production-ready en moins de 10 minutes.

Créer une clé API Retour au démarrage