Un même workflow, plusieurs points d’entrée
Le board relie les entrées, les modèles et les sorties. Sa publication en fige une version et définit ce que l’appelant peut fournir et récupérer. Le canal API REST rend cette version exécutable par HTTP.
Board → Publication → Version → Appel HTTP → Résultats
Préparer la publication
Construire et vérifier le board
Dans le board, reliez les entrées aux traitements puis aux sorties. Vérifiez le résultat dans Naquada avant de le proposer à vos outils.
Choisir les entrées et les sorties
Cliquez sur Publier. Dans la publication, définissez les champs exposés, leurs alias et les sorties retournées. Ces alias deviennent les clés de votre objet inputs.
Activer l’API et publier une version
Dans Activation, activez API REST. Publiez la version voulue pour ce canal. Une modification du board source ne modifie pas une version déjà figée.
Autoriser une clé
Dans Publications → Clés, créez une clé et donnez-lui accès à cette publication. L’activation du canal et l’autorisation de la clé sont toutes deux nécessaires.
Tester, puis passer en production
Une clé Sandbox (ctr_sbx_…) renvoie des résultats de test, sans exécuter les modèles ni dépenser de crédits. Une clé Production (ctr_prd_…) exécute le workflow et consomme les crédits du propriétaire.
Gardez la clé côté serveur
Appeler le workflow
Remplacez my-workflow par le slug de la publication et version=1 par une version publiée pour l’API. Le paramètre version est obligatoire. L’alias brief ci-dessous est un exemple : utilisez les alias de votre propre publication.
curl --request POST \
"https://api.naquada.tech/api/v1/generate/my-workflow?version=1" \
--header "Authorization: Bearer $NAQUADA_PUBLICATION_KEY" \
--header "Content-Type: application/json" \
--data '{"inputs":{"brief":"A short product introduction"},"async_response":true}'Avec async_response: true, l’API renvoie HTTP 202 et un resultId. Conservez cet identifiant pour suivre cette exécution. Les valeurs de réponse ci-dessous sont illustratives.
{
"resultId": "12345678-1234-4234-8234-123456789abc",
"status": "processing",
"version": 1
}Récupérer les résultats
Interrogez cette URL avec la même clé de publication. La réponse indique status ; les sorties exposées arrivent dans outputs lorsque le traitement est terminé. Dans l’exemple, renseignez NAQUADA_RESULT_ID avec le resultId reçu.
curl "https://api.naquada.tech/api/v1/generate/results/$NAQUADA_RESULT_ID" \
--header "Authorization: Bearer $NAQUADA_PUBLICATION_KEY"processing : en cours · waiting_for_approval : validation humaine attendue · completed : terminé · partially_completed : résultats partiels · failed : échec. Espacez les appels de suivi et prévoyez un délai maximal dans votre application.
Sans async_response: true, l’appel attend au plus deux minutes. Il peut donc répondre 202 si le travail continue : votre intégration doit également gérer ce cas.
Fichiers, notifications et limites
Pour les champs fichier, passez des URL HTTPS dans inputs. Un champ multiple accepte un tableau d’URL. Vous pouvez aussi envoyer du multipart/form-data : une partie data contient l’enveloppe JSON, et chaque fichier utilise le nom file_<alias>.
Pour être notifié à la fin, configurez un webhook autorisé. Vérifiez la signature X-Naquada-Signature sur le corps brut reçu. Les livraisons peuvent être réessayées : traitez les notifications de façon idempotente.
Les plafonds quotidiens et mensuels se règlent indépendamment. Ils ne s’appliquent qu’une fois activés avec une valeur positive. Les résultats de production consomment le budget du propriétaire de la publication.
Donner un workflow à votre assistant IA
Exposez une fonction dans votre service : elle reçoit les champs attendus, appelle la version publiée, suit resultId et restitue les sorties. Votre assistant choisit quand appeler cette fonction ; Naquada exécute le board préparé.
Découvrir les contrats accessibles
Listez les publications autorisées puis récupérez le contrat détaillé à partir de son identifiant de publication, et non de l’identifiant du board source. Utilisez ces champs pour décrire l’outil à votre assistant.
curl "https://api.naquada.tech/api/v1/generate/boards" \
--header "Authorization: Bearer $NAQUADA_PUBLICATION_KEY"
curl "https://api.naquada.tech/api/v1/generate/discovery/$NAQUADA_PUBLICATION_ID" \
--header "Authorization: Bearer $NAQUADA_PUBLICATION_KEY"Les clés de compte nqk_acc_… sont distinctes des clés de publication. Une invocation déléguée nécessite le droit externalizations:invoke, l’accès à la publication et X-Naquada-Externalization-Key-Id avec l’identifiant d’une clé de publication Production autorisée.
Voir le guide CLI et MCP