> ## 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.

# Primi passi

> Configura una chiave e usa cURL per ottenere un preventivo, eseguire uno strumento e recuperare il risultato.

## Panoramica

Questo esempio usa `web_search` per preparare una chiave, ottenere un preventivo gratuito, eseguire e recuperare il risultato. Bastano una shell compatibile con Bash e cURL, senza SDK specifici.

## Prerequisiti

Prepara questi cinque elementi:

* Un account NoimosAI con accesso a [Developer Platform](https://platform.noimosai.com)
* Un progetto Developer Platform con accesso API abilitato
* Una chiave sviluppatore con prefisso `nmp_` e autorizzazioni necessarie
* Una shell compatibile con Bash
* cURL, jq e uuidgen

Per attività a pagamento verifica anche saldo prepagato in USD e limiti mensili del progetto. Le autorizzazioni sono illustrate in [Autenticare le richieste](https://docs.noimosai.com/it/developers/api/authentication.md).

Se non compare alcun progetto accessibile, chiedi a un `OWNER` o `ADMIN` dell’organizzazione di crearne uno o aggiungerti. Le chiavi si creano nei progetti di cui fai parte.

## Eseguire l’API

Segui questi sette passaggi per la prima esecuzione.

### 1. Creare una chiave in Developer Platform

Un `ADMIN` o `DEVELOPER` del progetto può creare una chiave in [Developer Platform](https://platform.noimosai.com):

1. Accedi e seleziona il progetto.
2. Apri **Chiavi API** e scegli **Crea nuova chiave**.
3. Imposta nome descrittivo, scadenza e autorizzazioni, quindi crea la chiave.
4. Salva la chiave segreta in un luogo sicuro: viene mostrata una sola volta.

Questa guida richiede `project:read`, `tools:read`, `tools:execute` e `executions:read`. Per altri usi concedi solo le autorizzazioni necessarie.

### 2. Impostare chiave e URL di base

Salva chiave e URL di base in variabili d’ambiente per evitare segreti direttamente nella cronologia o nel codice sorgente.

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

> [!WARNING]
>
> La chiave viene mostrata solo alla creazione. Non salvarla in Git, documenti condivisi o JavaScript lato client.

### 3. Verificare il progetto della chiave

Verifica prima che la chiave corrisponda al progetto previsto di Developer Platform.

```bash theme={null}
curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/project" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY"
```

La risposta include in `data` ID organizzazione, ID e nome progetto. Se il progetto non è quello previsto, verifica la chiave prima di eseguire attività a pagamento.

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

### 4. Consultare gli strumenti disponibili

Recupera nomi, descrizioni, schemi, esempi, disponibilità e prezzi attuali.

```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
```

Verifica `executionEnabled` nella risposta generale e `available` nello strumento. Usa questa risposta come riferimento attuale, senza assumere quantità, modelli, schemi o prezzi fissi.

Filtra la risposta salvata per visualizzare solo `web_search`.

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

### 5. Ottenere un preventivo prima dell’esecuzione

Invia nome e argomenti dello strumento per ricevere versione prezzi e prenotazione massima. Questo non avvia attività a pagamento.

```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
```

Il preventivo restituisce `priceVersion` e `maximumChargeMicros` necessari per l’esecuzione. Riutilizzali senza modificarli o calcolarli. `maximumChargeMicros` è un intero in milionesimi di USD: 1 USD equivale a 1,000,000 micros.

```json theme={null}
{
  "data": {
    "tool": "web_search",
    "priceVersion": "...",
    "currency": "usd",
    "minimumChargeMicros": 0,
    "maximumChargeMicros": 0,
    "expiresAt": "..."
  }
}
```

Gli importi sopra illustrano solo il formato. Il prossimo passaggio legge i valori reali dalla risposta salvata.

### 6. Eseguire la richiesta preventivata

Mantieni strumento e argomenti del preventivo, aggiungendo versione prezzi e prenotazione massima. Includi una chiave di idempotenza per identificare la richiesta logica.

```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’esempio riusa il preventivo del passaggio 5 e genera una chiave con `uuidgen`. L’accettazione restituisce HTTP 202 e un ID di esecuzione.

```json theme={null}
{
  "data": {
    "id": "EXECUTION_ID",
    "tool": "web_search",
    "status": "queued",
    "reservedMicros": 0,
    "chargedMicros": 0
  }
}
```

La risposta include anche versione prezzi, output, errori e date. `chargedMicros: 0` durante l’elaborazione non significa che il costo sia stato definitivamente azzerato.

### 7. Interrogare lo stesso ID di esecuzione

Usa l’ID salvato al passaggio 6 e interrogalo a intervalli di almeno cinque secondi fino al completamento.

```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` e `waiting` indicano elaborazione in corso. Con `succeeded`, leggi `output` e `chargedMicros`. Consulta [Gestire esecuzione e fatturazione](https://docs.noimosai.com/it/developers/api/execution-and-billing.md) per altri stati.

> [!WARNING]
>
> Se la risposta è sconosciuta, non reinviare con una nuova chiave di idempotenza. Stesso corpo e stessa chiave recuperano l’esecuzione già accettata.

## Pagine correlate

Prosegui con le pagine pertinenti:

* [Autenticare le richieste](https://docs.noimosai.com/it/developers/api/authentication.md): autorizzazioni e conservazione delle chiavi
* [Gestire esecuzione e fatturazione](https://docs.noimosai.com/it/developers/api/execution-and-billing.md): attività lunghe, tentativi successivi e addebiti
* [Riferimento API](https://docs.noimosai.com/it/developers/api/reference.md): endpoint, stati e limiti
* [Documentazione](https://platform.noimosai.com/docs) Developer Platform: esempi aggiornati


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