> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noimosai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Premiers pas

> Configurez une clé et utilisez cURL pour obtenir un devis, exécuter un outil et récupérer le résultat.

## 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](https://platform.noimosai.com)
* 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](https://docs.noimosai.com/fr/developers/api/authentication.md).

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](https://platform.noimosai.com) :

1. Connectez-vous et sélectionnez le projet.
2. Ouvrez **Clés API**, puis **Créer une nouvelle clé**.
3. Définissez un nom explicite, une expiration et les autorisations, puis créez la clé.
4. 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.

```bash theme={null}
export NOIMOS_PLATFORM_API_URL="https://api.noimosai.com/noimosToolBridge"
export NOIMOS_PLATFORM_API_KEY="nmp_..."
```

> [!WARNING]
>
> 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.

```bash theme={null}
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.

```json theme={null}
{
  "data": {
    "developerOrganizationId": "...",
    "developerProjectId": "...",
    "name": "Example Project"
  },
  "requestId": "..."
}
```

### 4. Consulter les outils disponibles

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

```bash theme={null}
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`.

```bash theme={null}
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.

```bash theme={null}
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.

```json theme={null}
{
  "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.

```bash theme={null}
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.

```json theme={null}
{
  "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.

```bash theme={null}
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](https://docs.noimosai.com/fr/developers/api/execution-and-billing.md) pour les autres états.

> [!WARNING]
>
> 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](https://docs.noimosai.com/fr/developers/api/authentication.md) : autorisations et stockage des clés
* [Gérer exécution et facturation](https://docs.noimosai.com/fr/developers/api/execution-and-billing.md) : traitements longs, nouvelles tentatives et facturation
* [Référence de l’API](https://docs.noimosai.com/fr/developers/api/reference.md) : endpoints, états et limites
* [Documentation](https://platform.noimosai.com/docs) Developer Platform : exemples actuels


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.