Parcours vérifiable

Publications et API

Votre board devient un service appelable.

Construisez un workflow visuel, publiez une version et appelez-la depuis votre application, un script ou votre assistant IA.

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

Construisez un workflow visuel, publiez une version et appelez-la depuis votre application, un script ou votre assistant IA.

Préparer la publication

1

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.

2

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.

3

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.

4

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

Stockez la clé dans votre gestionnaire de secrets, ici sous NAQUADA_PUBLICATION_KEY. Votre navigateur ou votre assistant appelle votre service ; le service authentifie l’appel Naquada. Ne placez pas la clé dans le code public de votre site.

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.

Requête HTTP
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.

Réponse 202 · exemple
{
  "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.

Suivi du résultat
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.

Découverte des publications
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