Documentation

Référence API

Créer une exécution d'outil

POST/v1/tool-runs

Prend en charge flat (prix constant par appel), input (précalcul selon l'entrée) et usage (utilisation finale). pricing.quote_required impose ou non un devis ; requires_usage impose ou non un plafond de coût et l'attente de l'utilisation finale faisant autorité ; aucun ne se déduit de schema_version. Si metered_pricing est désactivé, seuls les nouveaux appels nécessitant l'utilisation finale sont limités ; les règles constantes/d'entrée sans cette exigence restent disponibles. La Key actuelle doit être autorisée pour l'outil ; identité d'exécution et résultats sont limités à la Key d'origine. Si l'interrupteur général des outils est désactivé, le catalogue est vide ; le catalogue anonyme ne constitue pas une autorisation d'exécution. Un nouvel appel exige version/input non vides et Idempotency-Key. Si la réponse de création est perdue sans run_id, répétez avec l'API Key, l'Idempotency-Key et le corps complet d'origine pour récupérer l'exécution existante, sans nouveau devis ni modification du plafond. La répétition d'une exécution acceptée ne dépend ni des interrupteurs actuels ni de la validité du devis. Avec run_id, consultez uniquement l'exécution initiale ; ne changez pas de clé pour une soumission inconnue.

Exécution après devis

Récupérez version, input_schema et pricing exacts dans les détails de l'outil. mode=flat est un prix constant par appel, mode=input un calcul préalable selon les entrées, et mode=usage un calcul selon l'utilisation finale ; schema_version décrit uniquement le format de stockage des règles.

Un nouvel appel avec quote_required=true exige d'abord un devis. Vérifiez tool_id/version renvoyés, puis enregistrez quote_id et la requête d'origine. Avec requires_usage=true, fournissez aussi max_cost_usd au moins égal à maximum_usd ; un plafond est facultatif pour les autres exécutions, mais tout plafond fourni est vérifié. Les exécutions constantes sans utilisation finale peuvent démarrer directement ; les règles d'entrée exigent un devis mais peuvent être réglées sans utilisation finale.

Le devis fige la source d'origine. Si la source par défaut change ensuite, le devis continue à utiliser l'ancienne tant que celle-ci et sa configuration restent valides. Pour un nouvel appel non soumis, quote_expired, quote_stale ou invalid_quote permettent de redemander un devis après vérification des entrées. Si l'exécution réussit mais que billing reste reserved, continuez à consulter l'utilisation finale ; une sortie réussie ne prouve pas le règlement.

Récupération si la réponse est perdue

Avant l'envoi, enregistrez l'identité API Key, l'Idempotency-Key et le corps complet d'origine. Si la réponse de création est perdue sans run_id, répétez POST /v1/tool-runs avec la même Key, la même clé de requête et la requête complète initiale ; conservez quote_id et max_cost_usd sans nouveau devis ni changement de clé. Une exécution existante restitue prioritairement l'enregistrement initial sans nouvel appel service, même si le devis a expiré ou si les nouveaux appels sont désactivés. Dès que run_id est connu, utilisez uniquement GET sur l'exécution initiale.

En cas de conflit d'idempotence, vérifiez la requête d'origine ; ne créez pas automatiquement une nouvelle opération payante en changeant de clé. Voir Gestion des erreurs, Facturation et Récupération asynchrone.

Authentification et autorisations

Utilisez votre clé GloopAPI actuelle. Les modèles, capacités et autorisations disponibles dépendent de son catalogue et de la documentation du point de terminaison.

Authorization: Bearer $GLOOP_API_KEY

Schémas d'authentification : BearerAuth

Requête

En-têtes de requête

  • Idempotency-KeystringObligatoire

    Conserve l'intention initiale sous la même Key. Après interruption réseau, consultez d'abord la récupération ; aucune répétition aveugle pour un état inconnu.

    Longueur minimale
    1
    Longueur maximale
    191

Corps de requête · application/json

Type
object
Champs obligatoires
tool_idversioninput
Propriétés supplémentaires
false

Corps de requête obligatoire

  • quote_idstringFacultatif

    Si pricing.quote_required=true, un devis valide est requis pour une nouvelle exécution ; facultatif pour un prix constant sans utilisation finale. Tout devis fourni voit ses liens vérifiés.

  • tool_idstringObligatoire

    ID d'outil dans le catalogue exécutable de la Key actuelle.

  • versionstringObligatoire

    Version du contrat, de la capacité ou de l'outil ; les exécutions utilisent la version d'outil du catalogue.

    Longueur minimale
    1
    Motif
    ".*\\S.*"
  • inputunknownObligatoire

    Doit respecter input_schema de cette version de l'outil. Seul du JSON normalisé est accepté ; champs supplémentaires tels que route_id administrateur interdits.

  • max_cost_usdstringFacultatifAutorise null

    Si pricing.requires_usage=true, toute nouvelle exécution exige un budget décimal en dollars valide et non null, au moins égal à maximum_usd du devis. Sinon facultatif, mais vérifié si fourni. Contrôle uniquement à la création.

Réponses et erreurs

HTTP 200

Renvoie 200 pour succeeded ou failed, lors du premier retour synchrone ou de la récupération idempotente. succeeded peut encore avoir billing.status=reserved en attendant l'utilisation finale ; HTTP 200 ne signifie pas comptabilité réglée.

application/json

Type
object
Champs obligatoires
idtool_idversionstatusoutputbillingresult_expiredcreated_atupdated_at
  • idstringObligatoire

    Identifiant public de l'objet, utilisé dans son chemin de détails.

  • tool_idstringObligatoire

    ID d'outil dans le catalogue exécutable de la Key actuelle.

  • versionstringObligatoire

    Version du contrat, de la capacité ou de l'outil ; les exécutions utilisent la version d'outil du catalogue.

  • statusstringObligatoire

    submitting/running/submission_unknown/succeeded/failed ; submission_unknown signifie soumission inconnue : ne changez pas Idempotency-Key pour répéter.

  • outputunknownObligatoire

    JSON défini par output_schema de l'outil ; ne présumez pas que le résultat existe après expiration.

  • error_codestringFacultatif

    Code d'erreur public utilisable pour choisir une branche de traitement.

  • billingobjectObligatoire

    État comptable indépendant, à ne pas remplacer par l'état de génération.

    Sous-champs de billing (7)
    • review_requiredbooleanFacultatif

      Les preuves comptables nécessitent une révision manuelle.

    • reasonstringFacultatif

      Raison publique de l'indisponibilité de l'action ou de la révision comptable.

    • usageunknownFacultatif

      Valeur JSON définie par le schema ou protocole de l'outil choisi ; ne présumez pas de champs fixes.

    • breakdownunknownFacultatif

      Valeur JSON définie par le schema ou protocole de l'outil choisi ; ne présumez pas de champs fixes.

    • statusstringObligatoire

      État actuel de l'objet ; évaluer séparément comptabilité et sauvegarde.

    • reserved_usdstringObligatoire

      Réservation maximale en dollars, sous forme de chaîne.

    • charged_usdstringObligatoire

      Montant actuellement confirmé en dollars, sous forme de chaîne.

    Branche allOf 1

    Type: object

    Obligatoire dans cette branche : status, reserved_usd, charged_usd

    • review_requiredbooleanFacultatif

      Les preuves comptables nécessitent une révision manuelle.

    • reasonstringFacultatif

      Raison publique de l'indisponibilité de l'action ou de la révision comptable.

    • usageunknownFacultatif

      Valeur JSON définie par le schema ou protocole de l'outil choisi ; ne présumez pas de champs fixes.

    • breakdownunknownFacultatif

      Valeur JSON définie par le schema ou protocole de l'outil choisi ; ne présumez pas de champs fixes.

    • statusstringObligatoire

      État actuel de l'objet ; évaluer séparément comptabilité et sauvegarde.

    • reserved_usdstringObligatoire

      Réservation maximale en dollars, sous forme de chaîne.

    • charged_usdstringObligatoire

      Montant actuellement confirmé en dollars, sous forme de chaîne.

  • result_expiredbooleanObligatoire

    Indique si le résultat a expiré ; comptabilité et idempotence restent conservées.

  • created_atintegerObligatoire

    Date de création en secondes Unix.

  • updated_atintegerObligatoire

    Dernière mise à jour en secondes Unix.

HTTP 202

État submitting, running ou submission_unknown : requête acceptée, mais comptabilité à évaluer séparément via billing.

application/json

Type
object
Champs obligatoires
idtool_idversionstatusoutputbillingresult_expiredcreated_atupdated_at
  • idstringObligatoire

    Identifiant public de l'objet, utilisé dans son chemin de détails.

  • tool_idstringObligatoire

    ID d'outil dans le catalogue exécutable de la Key actuelle.

  • versionstringObligatoire

    Version du contrat, de la capacité ou de l'outil ; les exécutions utilisent la version d'outil du catalogue.

  • statusstringObligatoire

    submitting/running/submission_unknown/succeeded/failed ; submission_unknown signifie soumission inconnue : ne changez pas Idempotency-Key pour répéter.

  • outputunknownObligatoire

    JSON défini par output_schema de l'outil ; ne présumez pas que le résultat existe après expiration.

  • error_codestringFacultatif

    Code d'erreur public utilisable pour choisir une branche de traitement.

  • billingobjectObligatoire

    État comptable indépendant, à ne pas remplacer par l'état de génération.

    Sous-champs de billing (7)
    • review_requiredbooleanFacultatif

      Les preuves comptables nécessitent une révision manuelle.

    • reasonstringFacultatif

      Raison publique de l'indisponibilité de l'action ou de la révision comptable.

    • usageunknownFacultatif

      Valeur JSON définie par le schema ou protocole de l'outil choisi ; ne présumez pas de champs fixes.

    • breakdownunknownFacultatif

      Valeur JSON définie par le schema ou protocole de l'outil choisi ; ne présumez pas de champs fixes.

    • statusstringObligatoire

      État actuel de l'objet ; évaluer séparément comptabilité et sauvegarde.

    • reserved_usdstringObligatoire

      Réservation maximale en dollars, sous forme de chaîne.

    • charged_usdstringObligatoire

      Montant actuellement confirmé en dollars, sous forme de chaîne.

    Branche allOf 1

    Type: object

    Obligatoire dans cette branche : status, reserved_usd, charged_usd

    • review_requiredbooleanFacultatif

      Les preuves comptables nécessitent une révision manuelle.

    • reasonstringFacultatif

      Raison publique de l'indisponibilité de l'action ou de la révision comptable.

    • usageunknownFacultatif

      Valeur JSON définie par le schema ou protocole de l'outil choisi ; ne présumez pas de champs fixes.

    • breakdownunknownFacultatif

      Valeur JSON définie par le schema ou protocole de l'outil choisi ; ne présumez pas de champs fixes.

    • statusstringObligatoire

      État actuel de l'objet ; évaluer séparément comptabilité et sauvegarde.

    • reserved_usdstringObligatoire

      Réservation maximale en dollars, sous forme de chaîne.

    • charged_usdstringObligatoire

      Montant actuellement confirmé en dollars, sous forme de chaîne.

  • result_expiredbooleanObligatoire

    Indique si le résultat a expiré ; comptabilité et idempotence restent conservées.

  • created_atintegerObligatoire

    Date de création en secondes Unix.

  • updated_atintegerObligatoire

    Dernière mise à jour en secondes Unix.

HTTP 400

Champs ou paramètres de requête invalides.

application/json

Type
object
Champs obligatoires
error

HTTP 401

Key absente, invalide, expirée ou révoquée.

application/json

Type
object
Champs obligatoires
error

HTTP 403

Autorisations IP, compte, modèle ou outil insuffisantes.

application/json

Type
object
Champs obligatoires
error

HTTP 404

Objet/capacité indisponible ou fonctionnalité désactivée.

application/json

Type
object
Champs obligatoires
error

HTTP 409

Conflit d'idempotence/devis, objet non prêt ou encore référencé.

application/json

Type
object
Champs obligatoires
error

HTTP 429

Limitation de débit des requêtes/de la file.

application/json

Type
object
Champs obligatoires
error

HTTP 500

Défaillance interne d'authentification ou de stockage des données.

application/json

Type
object
Champs obligatoires
error

HTTP 503

Service, tarification ou stockage indisponible.

application/json

Type
object
Champs obligatoires
error

Notes sur le point de terminaison

Exemple pour un outil requires_usage=true : remplacez quote_id et max_cost_usd ; le budget doit être une chaîne décimale valide en dollars, au moins égale à maximum_usd de ce devis. 0.01 est uniquement illustratif. Pour une règle d'entrée exigeant un devis sans utilisation finale, le budget est facultatif ; pour un prix constant sans utilisation finale, devis et budget sont facultatifs. Avant l'envoi, conservez l'identité de la Key, la clé de requête et le corps complet ; réutilisez-les si la réponse est perdue.