Premiers pas

Vue d’ensemble

Ce guide utilise web_search pour préparer une clé, obtenir un devis gratuit, exécuter l’outil et récupérer le résultat. Un shell compatible Bash et cURL suffisent, sans SDK propre à un langage.

Prérequis

Préparez les cinq éléments suivants :

Un compte NoimosAI permettant d’accéder à Developer Platform
Un projet Developer Platform avec accès API activé
Une clé de développeur commençant par nmp_ avec les autorisations nécessaires
Un shell compatible Bash
cURL, jq et uuidgen

Pour un traitement payant, vérifiez aussi le solde prépayé en USD et les plafonds mensuels du projet. Consultez les autorisations dans Authentifier les requêtes. Si aucun projet accessible n’apparaît, demandez à un OWNER ou ADMIN de l’organisation d’en créer un ou de vous y ajouter. Les clés se créent dans un projet auquel vous appartenez.

Exécuter l’API

Suivez ces sept étapes pour une première exécution.

1. Créer une clé dans Developer Platform

Un ADMIN ou DEVELOPER du projet peut créer une clé dans Developer Platform :

Connectez-vous et sélectionnez le projet.
Ouvrez Clés API, puis Créer une nouvelle clé.
Définissez un nom explicite, une expiration et les autorisations, puis créez la clé.
Enregistrez la clé secrète en lieu sûr : elle ne s’affiche qu’une fois.

Ce guide nécessite project:read, tools:read, tools:execute et executions:read. Pour d’autres usages, accordez uniquement les autorisations nécessaires.

2. Définir la clé et l’URL de base

Placez clé et URL de base dans des variables d’environnement pour éviter d’écrire des secrets directement dans l’historique ou le code source.

export NOIMOS_PLATFORM_API_URL="https://api.noimosai.com/noimosToolBridge"
export NOIMOS_PLATFORM_API_KEY="nmp_..."

La clé ne s’affiche qu’à sa création. Ne la stockez pas dans Git, un document partagé ou du JavaScript côté client.

3. Vérifier le projet de la clé

Vérifiez d’abord que la clé correspond au projet Developer Platform attendu.

curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/project" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY"

La réponse contient dans data l’identifiant d’organisation, l’identifiant et le nom du projet. Si le projet diffère, vérifiez la clé avant tout traitement payant.

{
  "data": {
    "developerOrganizationId": "...",
    "developerProjectId": "...",
    "name": "Example Project"
  },
  "requestId": "..."
}

4. Consulter les outils disponibles

Récupérez noms, descriptions, schémas, exemples, disponibilité et tarifs actuels.

NOIMOS_TOOLS_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY")

echo "$NOIMOS_TOOLS_RESPONSE" | jq

Vérifiez executionEnabled au niveau de la réponse et available pour l’outil. Prenez cette réponse comme référence actuelle, sans figer nombre d’outils, modèles, schémas ou tarifs. Filtrez la réponse enregistrée pour consulter uniquement web_search.

echo "$NOIMOS_TOOLS_RESPONSE" | jq \
  '.data.tools[] | select(.name == "web_search") | {
    name,
    description,
    available,
    inputSchema,
    example,
    models,
    price
  }'

5. Obtenir un devis avant exécution

Envoyez nom d’outil et arguments pour recevoir version tarifaire et réservation maximale. Cela ne lance aucun traitement payant.

NOIMOS_QUOTE_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/quote" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "tool": "web_search",
    "arguments": {
      "query": "content marketing trends",
      "count": 5
    }
  }')

echo "$NOIMOS_QUOTE_RESPONSE" | jq

Le devis renvoie priceVersion et maximumChargeMicros pour l’exécution. Réutilisez-les tels quels, sans calcul. maximumChargeMicros est un entier en millionièmes de USD : 1 USD vaut 1,000,000 micros.

{
  "data": {
    "tool": "web_search",
    "priceVersion": "...",
    "currency": "usd",
    "minimumChargeMicros": 0,
    "maximumChargeMicros": 0,
    "expiresAt": "..."
  }
}

Les montants ci-dessus illustrent uniquement le format. L’étape suivante lit les valeurs réelles de la réponse enregistrée.

6. Exécuter la requête du devis

Reprenez outil et arguments du devis, ajoutez version tarifaire et réservation maximale, puis une clé d’idempotence identifiant cette requête logique.

export NOIMOS_PRICE_VERSION=$(echo "$NOIMOS_QUOTE_RESPONSE" | jq -r '.data.priceVersion')
export NOIMOS_MAXIMUM_CHARGE_MICROS=$(echo "$NOIMOS_QUOTE_RESPONSE" | jq -r '.data.maximumChargeMicros')
export NOIMOS_IDEMPOTENCY_KEY=$(uuidgen)

NOIMOS_EXECUTION_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/web_search" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $NOIMOS_IDEMPOTENCY_KEY" \
  --data "$(jq -n \
    --arg priceVersion "$NOIMOS_PRICE_VERSION" \
    --argjson maximumChargeMicros "$NOIMOS_MAXIMUM_CHARGE_MICROS" \
    '{
      tool: "web_search",
      arguments: {
        query: "content marketing trends",
        count: 5
      },
      priceVersion: $priceVersion,
      maximumChargeMicros: $maximumChargeMicros
    }')")

echo "$NOIMOS_EXECUTION_RESPONSE" | jq
export NOIMOS_EXECUTION_ID=$(echo "$NOIMOS_EXECUTION_RESPONSE" | jq -r '.data.id')

L’exemple reprend le devis de l’étape 5 et génère une clé avec uuidgen. L’acceptation renvoie HTTP 202 et un identifiant d’exécution.

{
  "data": {
    "id": "EXECUTION_ID",
    "tool": "web_search",
    "status": "queued",
    "reservedMicros": 0,
    "chargedMicros": 0
  }
}

La réponse contient aussi version tarifaire, sortie, erreurs et dates. chargedMicros: 0 pendant le traitement ne signifie pas que celui-ci a été facturé gratuitement.

7. Interroger le même identifiant d’exécution

Utilisez l’identifiant enregistré à l’étape 6 et interrogez à au moins cinq secondes d’intervalle jusqu’à la fin.

while true; do
  NOIMOS_STATUS_RESPONSE=$(curl --fail-with-body \
    "$NOIMOS_PLATFORM_API_URL/tools/executions/$NOIMOS_EXECUTION_ID" \
    -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY")

  echo "$NOIMOS_STATUS_RESPONSE" | jq
  NOIMOS_STATUS=$(echo "$NOIMOS_STATUS_RESPONSE" | jq -r '.data.status')

  case "$NOIMOS_STATUS" in
    succeeded|failed|cancelled|needs_review) break ;;
  esac

  sleep 5
done

queued, running et waiting indiquent un traitement en cours. À succeeded, lisez output et chargedMicros. Consultez Gérer exécution et facturation pour les autres états.

Si la réponse est inconnue, ne renvoyez pas la requête avec une nouvelle clé d’idempotence. Le même corps et la même clé retrouvent l’exécution déjà acceptée.

Pages associées

Poursuivez avec les pages utiles à votre implémentation :

Authentifier les requêtes : autorisations et stockage des clés
Gérer exécution et facturation : traitements longs, nouvelles tentatives et facturation
Référence de l’API : endpoints, états et limites
Documentation Developer Platform : exemples actuels

API

CLI

Serveur MCP

Premiers pas

Vue d’ensemble

Prérequis

Exécuter l’API

1. Créer une clé dans Developer Platform

2. Définir la clé et l’URL de base

3. Vérifier le projet de la clé

4. Consulter les outils disponibles

5. Obtenir un devis avant exécution

6. Exécuter la requête du devis

7. Interroger le même identifiant d’exécution

Pages associées

​Vue d’ensemble

​Prérequis

​Exécuter l’API

​1. Créer une clé dans Developer Platform

​2. Définir la clé et l’URL de base

​3. Vérifier le projet de la clé

​4. Consulter les outils disponibles

​5. Obtenir un devis avant exécution

​6. Exécuter la requête du devis

​7. Interroger le même identifiant d’exécution

​Pages associées

Vue d’ensemble

Prérequis

Exécuter l’API

1. Créer une clé dans Developer Platform

2. Définir la clé et l’URL de base

3. Vérifier le projet de la clé

4. Consulter les outils disponibles

5. Obtenir un devis avant exécution

6. Exécuter la requête du devis

7. Interroger le même identifiant d’exécution

Pages associées