Démarrage rapide de l'API

Ce guide de démarrage rapide permet de vérifier qu'un backend peut s'authentifier et lire les données de votre compte. Vous avez besoin d'un forfait payant actif, d'un terminal avec curl et d'un accès à Tableau de bord → Paramètres → Développeur.

L'API v1 actuelle permet de gérer et de synchroniser des ressources. Ce n'est pas un transport de chat personnalisé : vous ne pouvez pas envoyer de messages en tant que visiteur. Les leads peuvent être créés, mis à jour et acceptés (leads:write), et un owner peut répondre à une conversation, la mettre en pause ou la reprendre (conversations:write).

1. Créer une clé à privilèges minimaux#

Créez une clé nommée Local API quickstart, sélectionnez account:read et sites:read, puis choisissez une durée de validité courte. Copiez immédiatement la clé en clair : elle ne sera plus affichée par la suite.

N'utilisez pas une clé de fournisseur d'IA, telle qu'une clé OpenRouter ou Speko. L'API publique exige une clé Make Agent Fast commençant par maf_live_.

2. La stocker pour ce terminal#

export MAF_API_KEY="maf_live_..."

Vérifiez que la variable existe sans afficher le secret :

test -n "$MAF_API_KEY" && echo "MAF_API_KEY is set"

Ne placez pas la clé dans un fichier .env, dans des exemples d'historique du shell, dans des fixtures de test ou dans un bundle de navigateur. Pour le code déployé, utilisez le gestionnaire de secrets de votre hébergeur.

3. Consulter le compte#

curl --fail-with-body --include https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

Statut attendu : 200 OK. Le corps de la réponse contient data.id, les informations sur le forfait et les droits d'accès, ainsi qu'un résumé du portefeuille. La réponse contient également x-request-id ; conservez cette valeur lorsque vous signalez une requête en échec.

{
  "data": {
    "id": "ACCOUNT_ID",
    "email": "owner@example.com",
    "plan": { "id": "pro", "status": "active" },
    "entitlements": { "site_limit": 3, "live_voice": true },
    "wallet": { "balance": 151 }
  }
}

Des champs peuvent être ajoutés sans modifier le chemin /v1. Ignorez les champs inconnus au lieu de rejeter la réponse.

4. Lister les sites#

curl --fail-with-body "https://makeagent.fast/api/v1/sites?limit=20" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

Les réponses de type collection utilisent cette enveloppe :

{
  "data": [],
  "has_more": false,
  "next_cursor": null
}

Si has_more est vrai, envoyez la valeur exacte de next_cursor comme paramètre de requête cursor de la requête suivante. Ne décodez pas les curseurs et n'en construisez pas.

5. Gérer une erreur structurée#

Supprimez temporairement l'en-tête Authorization et répétez l'appel à /me. La réponse doit être un 401 accompagné d'un code stable :

{
  "error": {
    "code": "authentication_required",
    "message": "Provide an API key in the Authorization bearer header.",
    "request_id": "6c0b2f2e-..."
  }
}

Le code de production doit se baser sur error.code, et non comparer message. Journalisez l'opération, le statut HTTP et l'identifiant de requête, sans journaliser la clé.

6. Effectuer une première écriture en toute sécurité#

Créez une clé distincte qui dispose également de sites:write, agents:write et knowledge:write ; n'étendez pas la clé de lecture du démarrage rapide. Suivez les recettes de l'API pour créer un site, ajouter des connaissances fiables et le publier en utilisant des clés d'idempotence explicites.

Échecs courants de la première requête#

Poursuivez avec Scopes et erreurs, la référence de l'API et les Limites de débit.