Recettes d'API

Ces recettes utilisent l'API REST brute, elles fonctionnent donc avant l'installation d'un SDK public. Définissez MAF_API_KEY dans l'environnement du serveur et remplacez les identifiants par ceux renvoyés par les étapes précédentes.

Recette : créer et publier un agent ancré dans vos sources#

Créez une clé d'API avec les portées sites:write, agents:write et knowledge:write. Ajoutez sites:read si l'automatisation doit aussi lister ou vérifier des sites.

1. Créer le site#

curl --fail-with-body https://makeagent.fast/api/v1/sites \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-site-2026-01" \
  -d '{
    "title": "Acme support",
    "slug": "acme-support",
    "type": "business",
    "template": "minimal",
    "content": {
      "headline": "Ask Acme support"
    },
    "persona_mode": "assistant",
    "languages": ["en"]
  }'

Une réponse réussie renvoie 201 Created, inclut le site sous data et renvoie le chemin canonique de la ressource dans l'en-tête Location. Enregistrez data.id sous le nom SITE_ID.

2. Configurer l'agent et la politique d'intégration#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-agent-2026-01" \
  -d '{
    "display_name": "Acme guide",
    "persona_mode": "assistant",
    "instructions": "Answer only from confirmed Acme sources. If the answer is missing, say that a teammate will follow up.",
    "languages": ["en"],
    "embed_enabled": true,
    "allowed_origins": ["https://www.acme.example", "https://staging.acme.example"]
  }'

Les origines autorisées sont des origines exactes : schéma, nom d'hôte et port facultatif. N'incluez ni chemin ni caractère générique final.

3. Ajouter une source de connaissances textuelle#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/knowledge" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-returns-2026-01" \
  -d '{
    "name": "Returns policy 2026-01",
    "text": "Customers may request a return within 30 days of delivery. Contact support before sending an item back."
  }'

Le texte collé doit comporter entre 5 et 200 000 caractères. Le même endpoint permet aussi d'explorer un site web avec { "url", "max_pages", "refresh_hours" } (max_pages jusqu'à 40) ou d'importer { "kind": "youtube" | "podcast" | "feed", "url" } ; ces sources multimédias nécessitent l'offre Operate ou Scale et renvoient 409 sur l'offre Launch. Le téléversement de fichiers reste réservé au tableau de bord.

4. Ajouter une FAQ structurée#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/faqs" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-faq-returns-2026-01" \
  -d '{
    "question": "How long do I have to return an order?",
    "answer": "You may request a return within 30 days of delivery.",
    "approved": true
  }'

5. Publier#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/publish" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-publish-2026-01" \
  -d '{"published": true}'

La réponse doit contenir {"data":{"id":"...","status":"published"}}. Ouvrez une intégration réelle et posez une question dont la réponse figure dans la source. La publication prouve que l'état de l'agent a changé ; elle ne prouve pas que la qualité de la source ou l'origine de l'intégration sont correctes.

Recette : paginer les leads en toute sécurité#

Utilisez une clé disposant de la portée leads:read. Traitez next_cursor comme une valeur opaque et encodez-la pour une URL.

const base = `https://makeagent.fast/api/v1/sites/${siteId}/leads`;
let cursor: string | null = null;

do {
  const url = new URL(base);
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.MAF_API_KEY}` },
  });
  if (!response.ok) throw await response.json();

  const page = await response.json();
  for (const lead of page.data) await exportLead(lead);
  cursor = page.next_cursor;
} while (cursor);

Ne décodez pas, ne modifiez pas, ne triez pas un curseur et ne le réutilisez pas pour une autre collection.

Recette : désactiver une intégration pendant un incident#

Utilisez la portée agents:write et conservez la même clé d'idempotence lors des nouvelles tentatives dues au réseau :

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: incident-2026-07-embed-off" \
  -d '{"embed_enabled": false}'

Une fois la réponse reçue avec succès, vérifiez que le lanceur ne s'initialise plus sur un hôte autorisé. Réactivez-le avec une nouvelle clé de résolution d'incident après avoir corrigé le problème d'origine, de contenu ou d'identifiants.

Liste de contrôle pour la production#

• Utilisez une clé distincte par service et par environnement.
• Conservez les identifiants de ressources et les clés d'idempotence avant d'envoyer une mutation.
• Définissez des délais d'expiration pour la connexion et la réponse.
• Respectez Retry-After et plafonnez le nombre de nouvelles tentatives.
• Journalisez le nom de l'opération, le statut HTTP et l'identifiant de requête, sans consigner de secrets ni de données personnelles.
• Testez sur un site hors production avant d'accorder des portées d'écriture en production.